How to Configure Apache to Use Custom Error Pages
IONOS editorial team4 mins
Creating custom Apache error pages allows you to make your design and branding visible on your entire website, among other things. We will show you how to do this.
Why should you have a custom error page?
Nobody wants HTTP errors to occur on their web server. However, this can happen from time to time depending on server load, internet connection or user input. The Apache web server provides a standard set of generic error pages for Error 404, HTTP Error 500 and other common errors.
However, configuring 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
Requirements
Apache and Ubuntu are among the most popular open-source platforms for hosting a web server. We show you how to install Apache under Ubuntu.
How to 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 (often /var/www/html/). Create a new page named my-404.html with the command:
sudo nano my-404.htmlPut the following into this file:
<html>
<head>
<title>My Custom 404 Error Page</title>
</head>
<body>
<p>Whoops, page not found! Sorry about that.</p>
</body>
</html>Save the file and exit Nano with the key combinations [Ctrl] + [O] and [Ctrl] + [X]. You can now view the file by going to http://example.com/my-404.html to ensure that it is displayed correctly.
How to create an Apache custom error page
Now you need to configure your Apache web server so that it also uses the error page you have just created. To do this, add an ErrorDocument directive. The syntax for this directive is:
ErrorDocument 404 [path to file]If you want to use this error page globally, the directive should be in the main Apache configuration file. If the page is only to be used for a virtual host instead (e.g. if your website is available in several languages), it must be in a VirtualHost command block. In this section we will mainly deal with the global configuration.
According to common practice, this Apache configuration file is usually:
- CentOS Stream 9 /etc/httpd/conf/httpd.conf
- Ubuntu 24.04 /etc/apache2/apache2.conf
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 Stream 9 sudo nano /etc/httpd/conf/httpd.conf
- Ubuntu 24.04 sudo nano /etc/apache2/apache2.conf
Insert the ErrorDocument in a suitable place. For example:
ErrorDocument 404 /my-404.htmlIf you only want to do this for a virtual host, you must scroll through the corresponding configuration file until you find the VirtualHost command block. Make sure that the directive is placed outside of directory command blocks. For example:
<VirtualHost *:80>
ServerName example.com
ErrorDocument 404 /my-404.html
<Directory "/var/www/example.com/html">
AllowOverride All
</Directory>
</VirtualHost>Save and exit the file, then restart Apache for the changes to take effect:
- CentOS Stream 9 sudo systemctl restart httpd
- Ubuntu 24.04 sudo systemctl restart apache2
Finally, test your error document by entering 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 is the 404 error, but you can also create custom error messages for other HTTP error messages. Apache allows you to configure your own error pages for all 4xx and 5xx error codes. An overview of the most important HTTP status codes can be found in another of our articles. A complete list of error codes can be found on Wikipedia.
