How to use custom error pages in Apache

Custom error pages in Apache keep “something went wrong” from looking like “the server fell down the stairs.” A branded 404 with a search box or a home link reduces dead-ends, and a calm 500 page prevents a transient outage from turning into a support-ticket stampede.

When a request fails, Apache can swap the default error response with a custom document via the ErrorDocument directive. Each mapping targets a local URL-path (internal redirect), an external URL, or a short inline string, and a local URL-path preserves the original HTTP status code while serving the custom body.

Local error documents must remain reachable inside the same site context, or error handling can recurse into more errors; the safest pattern is a simple static HTML page under the site’s DocumentRoot with minimal dependencies. The commands and paths below assume a Debian or Ubuntu layout (/etc/apache2/, apache2ctl, apache2), while RHEL-style installs commonly use /etc/httpd/ and httpd.

Steps to configure custom error pages in Apache:

Open a terminal with sudo privileges.

List enabled VirtualHost definitions to locate the active site configuration.

$ sudo apache2ctl -S
VirtualHost configuration:
*:80                   is a NameVirtualHost
         default server mysite.example (/etc/apache2/sites-enabled/000-mysite.conf:1)
         port 80 namevhost mysite.example (/etc/apache2/sites-enabled/000-mysite.conf:1)
##### snipped #####

On Debian and Ubuntu, entries under /etc/apache2/sites-enabled/ typically point to files in /etc/apache2/sites-available/.

Create the error document directory at /var/www/html/errors/.
```
$ sudo install -d -m 0755 /var/www/html/errors
```
Match the filesystem path to the site DocumentRoot in the relevant VirtualHost.

Create a custom 404 page at /var/www/html/errors/404.html.

$ sudo tee /var/www/html/errors/404.html >/dev/null <<'EOF'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>404 - Not Found</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <h1>404 - Not Found</h1>
  <p>The requested URL was not found on this server.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>
EOF

Create a custom 500 page at /var/www/html/errors/500.html.

$ sudo tee /var/www/html/errors/500.html >/dev/null <<'EOF'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>500 - Server Error</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <h1>500 - Server Error</h1>
  <p>A server error occurred while processing the request.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>
EOF

Open the target site configuration file.
```
$ sudo vi /etc/apache2/sites-available/000-mysite.conf
```
Related: Location for Apache VirtualHost configuration
Add ErrorDocument directives inside the relevant VirtualHost block.
```
<VirtualHost *:80>
  ServerName mysite.example
  DocumentRoot /var/www/html

  ErrorDocument 404 /errors/404.html
  ErrorDocument 500 /errors/500.html
</VirtualHost>
```
The second argument to ErrorDocument is a URL-path (like /errors/404.html), not a filesystem path (like /var/www/html/errors/404.html), and an error document that triggers the same error can cause recursion.
Save the configuration changes.
Exit the editor.
Check the configuration syntax.
```
$ sudo apache2ctl configtest
Syntax OK
```
Syntax OK confirms that Apache parsed the configuration without errors.

Related: How to test your Apache configuration
Reload the apache2 service.
```
$ sudo systemctl reload apache2
```
Use sudo systemctl restart apache2 when a reload fails or a full restart is required.

Related: How to manage the Apache web server service

Request a missing URL to confirm the custom 404 page is served with status 404.

$ curl -i -H 'Host: mysite.example' http://127.0.0.1/no-such-page
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
##### snipped #####
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>404 - Not Found</title>
##### snipped #####

Replace the Host value with the site ServerName when multiple VirtualHost entries share the same IP and port.

Author: Mohd Shakir Zakaria
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.

Discuss the article:

Comment anonymously. Login not required.