How to Configure Custom Error Pages in Apache

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.

Apache custom error pages are configured with the ErrorDocument directive. Point each status code to a local HTML page, dynamic handler, inline message, or (less commonly) an external URL, then reload Apache and verify that the original HTTP status is preserved. A typical configuration is ErrorDocument 404 /errors/404.html, ErrorDocument 403 /errors/403.html, and ErrorDocument 500 /errors/500.html.

What Apache’s ErrorDocument directive does

When Apache cannot complete a request normally, it generates an error response such as 404 Not Found, 403 Forbidden, or 500 Internal Server Error. The ErrorDocument directive replaces Apache’s standard response body with content you choose. Apache permits custom responses for any 4xx or 5xx status that it treats as an error condition.

#	Preview	Product	Price
1		Django Programming, In 8 Hours, For Beginners, Quick Start Guide (2nd Edition): Django Crash Course...	$2.99	Buy on Amazon
2		1st Grade United States History: Early American Settlers: First Grade Books (Children's American...	$4.99	Buy on Amazon

The official form is:

ErrorDocument <3-digit-code> <action>

The status code is the three-digit HTTP error code. The action is interpreted according to its form:

• A value beginning with / is a local URL, resolved inside the current server or virtual host.
• A valid absolute URL such as https://status.example.test/not-found is an external target. Apache redirects the client to it.
• Any other value is returned as response text. Multiword text must be enclosed in quotation marks.

For most sites, a local static page is the safest choice because it keeps the browser on the original URL, requires no application runtime, and makes it straightforward to retain the intended status code.

#1 Best Overall

Django Programming, In 8 Hours, For Beginners, Quick Start Guide (2nd Edition): Django Crash Course Textbook and Exercises (Textbooks in 8 Hours)

$2.99

Buy on Amazon

Choose the right error-page target

Do not use an external redirect merely to add branding. It changes the browser-visible request flow, can turn a 404 into a redirect followed by a 200 response, and removes the local redirect context that a handler can use to understand the original failure.

Prepare the files and directory layout

Place error documents inside the document tree served by the relevant virtual host. A simple layout is:

DocumentRoot /var/www/example/public

/var/www/example/public/
├── errors/
│   ├── 403.html
│   ├── 404.html
│   └── 500.html
├── index.html
└── ...

The URL in the directive is URL-relative, not a filesystem path. With the layout above, use /errors/404.html, not /var/www/example/public/errors/404.html.

Make each page self-contained. Error responses often occur when the requested path, rewrite rule, or application is already failing, so avoid dependencies that require the same broken route. Use absolute root-relative asset paths such as /assets/error.css rather than relative paths such as ../assets/error.css; the browser is handling a URL under /errors/, and relative references can resolve somewhere unexpected.

Keep the error files reachable without authentication and without a deny rule. If /errors/404.html itself produces a 403 or 404, Apache can return a second error, a blank response, or a loop instead of your intended page.

Configure custom pages in a virtual host or server configuration

Server and virtual-host configuration is preferable when you administer Apache directly. Add the directives inside the appropriate virtual host, or in the server configuration when the behavior should apply globally:

<VirtualHost *:443>
    ServerName example.test
    DocumentRoot /var/www/example/public

    ErrorDocument 403 /errors/403.html
    ErrorDocument 404 /errors/404.html
    ErrorDocument 500 /errors/500.html
</VirtualHost>

Ensure that the files are under the DocumentRoot (or another path allowed by the virtual host) and that Apache’s user can read them. If several virtual hosts share one server, put the directives in the host that actually receives the request. A frequent mistake is editing one virtual host while DNS, SNI, or the Host header sends the request to another.

After saving the configuration, validate it before reloading:

apachectl configtest

Some platforms provide a distribution-specific equivalent, but the goal is the same: a syntax check that reports Syntax OK (or the platform’s successful result). Reload Apache through the normal service mechanism for your operating system. Do not skip the validation step; one malformed directive can prevent the new configuration from loading.

Configure the same behavior in .htaccess

Shared hosting often does not allow edits to the virtual-host file. In that case, put the directives in an .htaccess file in the directory whose URL space should use them:

ErrorDocument 403 /errors/403.html
ErrorDocument 404 /errors/404.html
ErrorDocument 500 /errors/500.html

ErrorDocument is permitted in directory context and in .htaccess only when the server administrator allows the FileInfo override class. A typical virtual-host setting is:

<Directory /var/www/example/public>
    AllowOverride FileInfo
</Directory>

The exact AllowOverride policy may be stricter or broader. If the host uses AllowOverride None, an .htaccess directive will not take effect and may produce a server error. You cannot fix that from the file itself; the administrator must change the directory policy or add the directive to the main configuration.

File placement matters. An .htaccess file applies to its directory and descendants, subject to Apache’s directory-merge rules. Put it below the correct document root, confirm that Apache is allowed to read per-directory configuration there, and make sure the request is handled by the expected virtual host.

Use local pages while preserving the original status

For a local target, Apache internally maps the failed request to the error URL. The client should still receive the original error status, while the body comes from the local document. This distinction matters: a polished 404 page that returns HTTP 200 is treated as a successful page by crawlers, monitoring systems, caches, and client software.

Apache supplies redirect context to local targets through environment variables whose names begin with REDIRECT_. The following are guaranteed for a local error-document request:

• REDIRECT_URL — the original URL that failed.
• REDIRECT_STATUS — the status that caused the internal redirect.
• REDIRECT_QUERY_STRING — the original query string.

Other request headers are carried only when they existed in the original request. A dynamic handler can use these variables to display a useful message, log the failed path, or select a language without guessing which URL caused the error. External targets do not receive this local redirect context.

Build static 403, 404, and 500 pages

404 Not Found

Use 404 when Apache cannot map the requested URL to existing content. Keep the page useful without pretending that the missing URL was successful. Provide a link to the home page, a site search if one exists, and a short explanation. Avoid server paths, stack traces, or details that disclose internal configuration.

Rank #2

1st Grade United States History: Early American Settlers: First Grade Books (Children's American History Books)

$4.99

Buy on Amazon

ErrorDocument 404 /errors/404.html

403 Forbidden

Use 403 when the server understood the request but refuses access, for example because of authorization or directory restrictions. Do not make the error page itself subject to the same authorization rule. A static page can explain that the visitor lacks permission without revealing whether a sensitive resource exists.

ErrorDocument 403 /errors/403.html

500 Internal Server Error

Use 500 for an unexpected server-side failure. Keep this page independent of the application code that failed. In production, show a generic message and an incident reference rather than a stack trace or environment variables. Test a 500 handler only in a controlled environment; deliberately breaking production code can hide the original fault and create a second outage.

ErrorDocument 500 /errors/500.html

Use a dynamic handler when the page needs context

A local CGI, PHP, or other dynamic endpoint can inspect the redirect variables and render a response tailored to the failed request:

ErrorDocument 500 /errors/handler.php

A CGI handler should emit a Status: header so the original error status propagates to the client. The same principle applies to application runtimes that generate their own response headers: do not let the handler default to 200. A handler that intentionally redirects the visitor with a Location: header must also send an appropriate status such as 302 Found; otherwise clients may interpret the response incorrectly.

Dynamic error handlers add operational risk. They can fail because the interpreter is unavailable, consume resources during an outage, or invoke the same rewrite and authorization logic that caused the first error. For that reason, a static page is usually the better default, with a dynamic handler reserved for a genuine need such as localized content, request identifiers, or integration with an incident system.

Prevent rewrite, authorization, and recursion loops

Error documents are ordinary URLs from Apache’s point of view. Rewrite rules, front-controller routing, access controls, and directory settings can therefore process them again. Exclude the error directory from rules that would send it back to the application or deny it:

RewriteEngine On
RewriteRule ^errors/ - [L]

The exact rewrite strategy depends on your existing rules, so place the exception where it prevents the error path from entering the failing rule set. Also check that:

• The error files exist with the exact case used in the URL.
• Apache can traverse every parent directory and read the files.
• The error directory is not protected by an authentication or IP restriction.
• A content-security policy, MIME rule, or forced download setting is not breaking the page.
• The error handler does not call an unavailable database or service during the original outage.

In access and error logs, a repeated sequence of internal redirects, permission failures, or a second 404 for the error URL is a strong indication of a loop or inaccessible target.

Account for reverse proxies and upstream applications

If Apache proxies requests to an application server, the upstream response may replace Apache’s own error body. Apache’s ProxyErrorOverride directive controls whether Apache supplies its configured error documents on behalf of proxied origins. Without the appropriate proxy configuration, you may edit ErrorDocument successfully and still see the application server’s default page.

Test the complete request path, not only a static file served directly by Apache. Confirm which layer generated the status and body by checking response headers, the proxy configuration, and both Apache and application logs. If the upstream intentionally returns a custom body, decide whether that body or Apache’s centralized pages should be authoritative for each status.

Enable Apache’s multilingual error documents

Apache includes translated error documents and a configuration include named conf/extra/httpd-multilang-errordoc.conf. Enabling that feature allows language negotiation based on the browser’s language preference. Apache’s multilingual setup requires both mod_include and mod_negotiation.

This option is different from pointing every status at one hand-written page. Confirm that the required modules are loaded, that the include is enabled in the active configuration, and that your language variants are available under the expected document paths. Test with requests carrying different Accept-Language headers, and verify that the response status remains the original 4xx or 5xx code.

Verify status codes and response bodies

Always test the status and the rendered body together. A browser can display a friendly page even when the server returns the wrong code.

1. Run apachectl configtest (or the equivalent command supplied by your platform).
2. Reload Apache using the host’s normal service process.
3. Request a path that definitely does not exist:

curl -i https://example.test/does-not-exist

Confirm that the response begins with HTTP/1.1 404 (or the negotiated protocol equivalent) and that the body is your 404 document.

4. Exercise a controlled access-denied path and verify that it remains 403.
5. In a safe test environment, trigger a controlled server or application failure and verify that the 500 handler does not emit 200.
6. Inspect access and error logs for permission errors, rewrite loops, failed includes, or a second error while Apache renders the document.
7. If the result is unexpected, check the response from the exact hostname and scheme users access; a different virtual host or proxy may be answering.

Troubleshoot the most common failures

The default Apache page still appears

• Confirm the directive is in the active virtual host or in an .htaccess file that applies to the requested directory.
• For .htaccess, ask the administrator to verify that AllowOverride includes FileInfo.
• Check that Apache was reloaded after a server-configuration change.
• Request the correct hostname and HTTPS endpoint so you test the intended virtual host.
• Check whether a reverse proxy or upstream application is replacing Apache’s body.

The custom page produces another 404 or 403

• Verify the file exists below the active document root.
• Check URL spelling and case; Linux filesystems are commonly case-sensitive.
• Ensure Apache can traverse parent directories and read the file.
• Remove authentication, deny rules, or rewrite processing from the error path.

The page displays but the status is 200

• Inspect the headers with curl -i, not only the browser screen.
• If a dynamic handler is used, emit the original status through the runtime’s supported mechanism; CGI handlers need a Status: header.
• Check whether application code or a proxy converted the error into a normal response.

An external error URL behaves unexpectedly

An external ErrorDocument target is a client redirect, not an internal body substitution. The browser leaves the original URL, and the destination does not receive Apache’s local REDIRECT_ variables. Use a local target when preserving the original request and status is important.

Design and security requirements for production pages

• Keep the message concise and explain the next useful action.
• Offer navigation that does not depend on the missing route.
• Use accessible headings, sufficient contrast, keyboard-friendly links, and meaningful document language.
• Do not print filesystem paths, configuration values, stack traces, database errors, or request headers.
• Keep the page lightweight so it can render during a partial outage.
• Do not assume JavaScript, cookies, a session, or a working API is available.
• Log diagnostic detail on the server, while showing visitors only a safe reference or support instruction.
• Review cache behavior carefully. A 404 or 500 response should not be cached for longer than your recovery and deployment process can tolerate.

Further reading and version awareness

Apache Cookbook, 2nd Edition (O’Reilly Media, December 2007) contains older Apache 2.0 and 2.2-era examples. It can provide historical context, but validate every directive and behavior against the current Apache HTTP Server 2.4 documentation before applying it to a modern installation.

Quick Recap

Bestseller No. 1

Django Programming, In 8 Hours, For Beginners, Quick Start Guide (2nd Edition): Django Crash Course Textbook and Exercises (Textbooks in 8 Hours)

$2.99

Bestseller No. 2

1st Grade United States History: Early American Settlers: First Grade Books (Children's American History Books)

$4.99

Configuration checklist

• Choose a local static page unless request-aware logic is genuinely required.
• Create reachable files such as /errors/404.html, /errors/403.html, and /errors/500.html.
• Add ErrorDocument in the correct virtual host, directory, or permitted .htaccess file.
• Use AllowOverride FileInfo (or the administrator’s approved equivalent) when configuring through .htaccess.
• Exclude the error path from failing rewrites and authorization rules.
• Run a configuration test before reload.
• Verify every response with headers, body, and logs.
• Check proxy behavior when Apache is not the final response generator.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.