Custom HTTP Error Pages in cPanel

cPanel: The Secrets To Successful HTTP Error Page

Learn about the HTTP status codes cPanel natively supports and how to create & customize HTTP error pages for your cPanel-hosted domain … the right way.

You know that feeling.

You have googled something.

Have transversed from page 1 of the results and now, on page 10.

Then you saw a title and a description that matches exactly what you have spent the past 20 minutes searching for.

With unbridled excitement, you click the link … then crickets.

The page is not available.

And there is no information on what may have happened to it or what to do next.

Quite frustrating, isn’t it?

But it happens to the best of us.

This is because, in the life of a website, pages get moved, deleted, misnamed, or redirected.

As a hosting account admin, a website, and/or business owner, you do not want your visitors to meet a missing page and be unable to figure out what to do next.

Besides the fact that the visitor may not return, search engines will likely delist or remove web pages with anything less than 200 (successfully completed) responses.

Creating custom error messages (see a complete list of HTTP codes at:

enables you to provide a friendly (and/or a more informative response) when visitors to your site cannot access the content they requested.

This can either be done by serving an error page file, returning another resource, or redirecting to a URL.

Our web servers do provide generic error responses in the event of:

  • status codes starting with 4 (client errors), for example, 403
  • status codes starting with 5 (server errors), for example, 503.

But these responses are rather stark, uninformative, and can be intimidating to site users.

The basic features that a good error page should be able:

  • to explain (in plain language) to a user why the page they’re looking for can’t be found
  • have the same look and feel (including navigation) as the rest of your site
  • have a search functionality
  • have a link to your homepage and sitemap
  • have a call to action on what to do next (for example, a way to report a broken link)
  • be able to use a 503 (service unavailable with “site is temporarily down”) or 301 (permanent redirect) or 307 (temporary redirect) to tell search engines and visitors what the status should be.

Normally, you will add something like this below to the .htaccess file to serve with error messages:

ErrorDocument 401 /unauthorized.html

ErrorDocument 403 /forbidden.html

ErrorDocument 404 /notfound.html

ErrorDocument 500 /server-error.html

ErrorDocument 503 /service-unavailable.html

However, the recommended way to create Error pages in cPanel is to use the feature at Advanced >> Error Pages.

These are highly customizable and allow you to:

  • customize the HTTP error pages sent to clients, based on the status code of the server response.
  • use these to inform visitors about problems when they attempt to access your site.
  • meet one or two suggestions from the recommendation above

Before proceeding to customize an error page in cPanel, we highly suggest that you create a “webmaster” email address.

For example, you can create webmaster@$

This is crucial in that even if your error page is not a custom one with links to contact you when things break, your visitors can at least send an email to you regarding an issue.

When the email address is ready, perform the following steps:

Select the domain for which you wish to edit an error page from the Managing: menu.

If your hosting account manages more than one domain, select the right domain.

Click the error status code for which you wish to edit its error page.

The defaults you will readily see are:

  • 400 (Bad request)
  • 401 (Authorization required)
  • 403 (Forbidden)
  • 404 (Not found)
  • 500 (Internal server error)

To see the other error status code, click the Show All HTTP Error Status Codes tab.

Select the desired error status code.

Enter the message you want shown in the text box.

Enter additional HTML code to further customize your error pages. This is where you can allow your imagination to run free.

For each of the error statuses, just think about what you would love to see as the “next step” if you are the visitor.

Create, test the HTML code and then add it to the HTML editor.

Finally, click Save.

If you visit File Manager or use “% ls -al public_html”, you will see all the $error.shtml you just created:

cPanel HTTP Error Pages in File Manager

You have successfully created an error page for your cPanel-hosted domain.

Commonest HTTP Error Status

HTTP Error 401 (Unauthorized)

This error happens when a website visitor attempt to access a restricted web page but is authorized to do so.

You will often see this when an HTTP Authentication is required to view a file.

While slightly similar to “403 Forbidden Response” (indicating that access must be explicitly allowed before proceeding), this error is due to missing authentication credentials needed to access the page.

If you are the website owner or the hosting admin, try using “curl” to test access:

% curl -IL

Then check for HTTP/1.1 or HTTP/2 401 Unauthorized

If you are sure that you have the correct credentials, try to clear your device/browser cache, visit the page via Private/Incognito Mode or restart the device before re-attempting the process.

If you have previously used cPanel >> Files >> Directory Privacy to restrict access to the location, double-check the content of the generated .htaccess file to see if it aligns with what you expected.

HTTP Error 403 (Forbidden)

The difference between this error and 401 is “forbidden” and “unauthorized”.

This is a response status code that indicates that while the server understands the request, it simply has refused to authorize it.

You may run into this error if your hosting account is newly created (or if you have just added an add-on domain) and haven’t added a file to the directory for the server to serve.

To resolve this, simply upload an index.html or index.php file to the directory, revisit the website in a browser and you will see that the error has disappeared.

You will run into this error if the server has mod_evasive installed and enabled.

Apache will block requests & log the action if a user makes too many requests in a short period of time.

You can also see this error if the “/home/user/public_html/.well-known/pki-validation/” directory is not accessible or being blocked.

To verify if this directory has the correct permission and access, use your SSH Terminal or File Manager to create a file in /.well-known/pki-validation/.

Then use the “curl” command:

% curl -IL http://$

If everything is OK, you will receive a 200 OK response.

If not, then you will receive a 403 instead.

HTTP Error 404 (Not Found)

Probably the commonest among the commonest errors.

On cPanel servers, this error message can either indicate that:

the requested file could not be found in the specified path or

that there is an invalid rewrite rule that is causing the application being used to access it incorrectly or

that there is a typo in the URL the visitor is using to access the file

If you are the website owner or hosting admin, you can quickly check if the 404 error by renaming the .htaccess files in each directory up to the website’s document root with:

mv -vi /home/user/.htaccess{,.bak}

mv -vi /home/user/public_html/.htaccess{,.bak}

You can also achieve the same result by using cPanel “File Manager“, enabling the “Show Hidden Files” option, and then using the “Rename” function.

If you need to visually confirm whether the requested file is missing or exists in the path, you can visit Metrics >>Errors which works for both NGINX® with Reverse Proxy and Apache®.

The best way to ensure that this does not negate the experience you want your visitors to have is to create a custom 404 page and provide guidance to the user on what to do next.

HTTP Error 500 (Internal Server Error)

This error is a generic “catch-all” error message that pops up when a web server encounters some form of an internal error or an unexpected condition that prevented it from fulfilling the request.

A typical example would be if you are trying to view an HTML file that is placed inside of the cgi-bin directory of your cPanel account.

Given that the cgi-bin directory is a special directory that only allows CGI scripts and other related files (such as txt files) to be viewed from it, you will meet a 500 error.

Another typical instance that our Migration team often runs into is where a customer is using WordFence, and the plugin is trying to access wordfence-waf.php at an incorrect location.

This might be after a cPanel account is transferred or a cPanel Account account name is changed.

In the case of WordPress + WordFence WAF, you may try to edit the .user.ini file in your home folder (i.e. /home/$username) and correct the auto_prepend_file path value:

; Wordfence WAF
auto_prepend_file = '/home/$username/public_html/wordfence-waf.php'
; END Wordfence WAF

In most cases, if you are hosting your domain with Web Hosting Magic, please report all 5XX errors to our technical support team.

The machine’s log error should have more details about the request and will use this to ensure that the error is taken care of.

HTTP 503 (Service Unavailable)

On our hosting platform, the likeliest cause for this is when a site has exceeded the limit of its number of concurrent connections.

A similar error that may also appear would be 508 Service (Temporary Unavailable).

This is most likely a result of a restriction that the system automatically initiated due to high memory usage or a maximum number of processes exceeded.

When that happens, the user will receive 503 errors because the server cannot execute the script.

The rule of the thumb is:

If the site is limited by CPU or IO, then the site will start responding slower.

If the site is limited by memory or number of process limits, then the user will receive 500 or 503 errors that the server cannot execute the script.

The simplest way to address this is to wait for a few seconds for things to things to normalize.

Or consider upgrading the hosting package that will allow more resources to the account.

If the account is using PHP-FPM instead of mod_lsapi (which is our default), then the likely explanation is that Apache and PHP-FPM are being overloaded with requests.

To sort this out, adjustments need to be made to PHP-FPM pool limits.

A 503 error can also appear when the ~/public_html/ directory is missing a .htaccess file.

If that is the case, just add .htaccess to the directory to get the issue resolved.

We hope this has helped you understand how to use HTTP status codes to keep your website visitors and search engines happy.



, ,