Using Custom Error 404 with Apache

custom 404

When you manage a website, a great deal of time is spent customizing the software, running it, and tweaking the layout and design to match the ideas you have for how it should look. Normally we only think about the parts of the website we expect visitors to see. Unfortunately there are some common pages that can be missed: the error pages.

Error Pages

While in an ideal world no one should ever see an error page on your website, there are a number of factors that could cause them to be shown. One is shown as a result of user error, when someone incorrectly types in a link they have tried to remember. In this tutorial we’ll look at how we can go about serving custom error pages with the Apache web server instead of the standard and plain built-in ones. This means you can make your error pages match the rest of your site design, and even include navigation to link visitors back to important pages on your site.

The errors we’ll be concentrating on here are these common ones that may often be encountered by a browser:

401 – Unauthorized: This error is seen for pages where authentication is required but the user has not given authentication details.

403 – Forbidden: This error is given for pages where authentication is required and incorrect details have been provided.

404 – Not Found: This error is given when the web server is unable to locate the file that the visitor has requested.

500 – Internal Server Error: This is given when there is an error processing the request but there isn’t an applicable and more specific error to provide.

There are many more errorsthan this, but most are unlikely to be encountered except for a number of specific web server implementations.

To make this work, the first thing you need to do is create web pages for the errors that need to be served. First you’ll need to go to your website’s webroot directory on your server. In that directory we’ll create 4 files, named after the different errors, so 401.html, 403.html, 404.html, and 500.html. Into these you’ll need to put the HTML code to create your error pages. If you don’t know HTML then an easy way of doing this is to open your website in your web browser, right click on the page and select “view source”. Copy and paste the HTML content from the page into a text editor and then find the content from the page and replace it with the text you wish to use for your custom error page. You can test how this looks by saving it to your local computer using the relevant filename, and opening it in your web browser.

Once you are happy with the HTML content for your error pages, you can paste that into the files on your server. You can then test the pages work by navigating to them in a web browser, for example:


You’d need to replace “” with your website’s domain name, of course. If the page loads without problem then it’s ready to be used. The last thing to do is to configure Apache to serve your error documents instead of the standard ones. There are two ways to do this: one is using a .htaccess file which is placed in your website’s web root directory and is normally used when you don’t have access to edit the virtualhost files for the website such as with shared hosting. The other method (which is preferred if you are the administrator of the system) is to place the ErrorDocument directives at the end of the virtualhost file before the trailing </VirtualHost> line. Below is the text you would need to paste into the file to make it work:

ErrorDocument 401 /401.html

ErrorDocument 403 /403.html

ErrorDocument 404 /404.html

ErrorDocument 500 /500.html


Save and exit the file edited. If you used the .htaccess file then you don’t need to do anything else for it to work. If you place the directives in the virtualhost file you will need to reload Apache with the following:

On CentOS/Red Hat systems:

sudo systemctl reload httpd

On Debian/Ubuntu systems:

sudo systemctl reload apache2

You can now test that it works by navigating to a page that doesn’t exist on your website, after which you should be served your new custom 404 error page.