How to configure Apache to use custom error pages

Learn how to set up custom error pages in Apache. The Apache web server provides a default set of generic error pages for 404, 500, and other common Apache errors.

However, creating custom error pages allows you to:

  • Continue your branding on these pages
  • Integrate their design into the look and feel of your website
  • Direct lost visitors to their intended destinations
  • Provide error pages in languages other than English


  • Cloud Server running Linux (CentOS 7 or Ubuntu 14.04)
  • Apache installed and running
vServer (VPS) from IONOS

Low-cost, powerful VPS hosting for running your custom applications, with a personal assistant and 24/7 support.

  • 100 % SSD storage
  • Ready in 55 sec.
  • SSL certificate

Create the custom error page

First, you will need to create the custom error page. For testing purposes, we will create an example error page to handle 404 errors.

Use SSH to connect to your server and go to your website's document root. Create a new page named my-404.html with the command:

sudo nano my-404.html

Put the following into this file:

<title>My Custom 404 Error Page</title>
<p>Whoops, page not found! Sorry about that.</p>

Save and exit the file.

You can view the file by going to "" to make sure it is displaying correctly.

Configure Apache to use the custom error page

To tell Apache to use a custom error page, you will need to add an ErrorDocument directive. The syntax for this directive is:

ErrorDocument 404 [path to file]

For this example, since the my-404.html file is in the site's document root, we will be adding the directive:

ErrorDocument 404 /my-404.html

This directive needs to go inside the VirtualHost command block in the site's main Apache configuration file.

By common convention, this Apache configuration file is usually:

  • CentOS 7/etc/httpd/conf.d/
  • Ubuntu 14.04/etc/apache2/sites-available/

The location and filename of a site's Apache configuration file can vary based on how you or your server administrator has set up hosting.

Edit this file with your editor of choice, for example with the command:

  • CentOS 7sudo nano /etc/httpd/conf.d/
  • Ubuntu 14.04sudo nano /etc/apache2/sites-available/

Scroll through the file until you find the VirtualHost command block, which will look like:

<VirtualHost *:80>
    <Directory "/var/www/">
    AllowOverride All

Add the ErrorDocument to the VirtualHost command block, but be sure to put it outside any Directory command blocks. For example:

<VirtualHost *:80>
ErrorDocument 404 /my-404.html
    <Directory "/var/www/">
    AllowOverride All

Save and exit the file, then restart Apache for the changes to take effect:

  • CentOS 7sudo systemctl restart httpd
  • Ubuntu 14.04sudo services apache2 restart

Finally, test your error document by going to an invalid URL for your website. You will be redirected to your new custom 404 page instead.

Other HTTP error codes

The most common custom error page is for a 404 error. However, you may want to create custom error pages for other Apache errors as well.

These pages can be configured for any 4xx or 5xx error code. A full list of these HTTP error codes can be found on Wikipedia.

We use cookies on our website to provide you with the best possible user experience. By continuing to use our website or services, you agree to their use. More Information.
Page top