Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Your custom 404 page does not appear and Apache shows its own

ErrorErrorDocument 404 /errors/not-found.html

Short answer

Apache shows its default 404 when the ErrorDocument line is never read or its argument is read the wrong way. The usual reasons: AllowOverride does not include FileInfo, the target is a full URL so Apache redirects instead of serving it, a multi-word text lacks quotes, or the page sits behind a proxy.

  • Applies to Apache 2.4, Amazon Linux 2023, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request a URL that does not exist and read the status line and headers. A 404 with the default body, a 302 or a 200 each point to a different cause below.

    curl -i https://example.com/this-page-does-not-exist
  2. 2Match what you see, then jump to its fix

    1. 1The default Apache 404 body, and the line in .htaccess has no effect at allAllowOverride does not allow FileInfo, so .htaccess is not read for this directiveFix
    2. 2Status 302 and a Location header instead of 404The target is a full URL, so Apache sends a redirect and not a 404Fix
    3. 3The page shows odd text, or only the first word, or Apache reports a syntax error on reloadA text message with several words has no quotesFix
    4. 4The 404 body comes from your app, not from the file in ErrorDocumentThe request is proxied and the backend's own 404 winsFix

What does the error look like?

  • ErrorDocument 404 /errors/not-found.html
  • The browser still shows 'Not Found - The requested URL was not found on this server'
  • The custom page opens at its own address but not for a missing URL
  • A 302 redirect appears where a 404 status was expected

Cause 1 of 4

AllowOverride does not allow FileInfo, so .htaccess is not read for this directive

1Check

ErrorDocument is allowed in .htaccess only when AllowOverride permits the FileInfo group for that directory. Look at the AllowOverride value for your document root.

grep -R -n "AllowOverride" /etc/httpd /etc/apache2 2>/dev/null

2Fix

Set AllowOverride FileInfo (or All) in the Directory block that covers the site, then reload Apache with apachectl graceful. Better still, move the ErrorDocument line into that block and drop .htaccess for it.

<Directory "/var/www/html">
    AllowOverride FileInfo
</Directory>

3Verify

Reload Apache and request a missing URL again.

sudo apachectl configtest && sudo apachectl graceful
curl -i https://example.com/this-page-does-not-exist

Confirmed by httpd.apache.org

Did this fix it?

Cause 2 of 4

The target is a full URL, so Apache sends a redirect and not a 404

1Check

If the ErrorDocument argument starts with http:// or https://, Apache treats it as an external URL, even on the same host. Check the line.

grep -n "ErrorDocument" .htaccess

2Fix

Use a local path that starts with a slash, relative to DocumentRoot. The client then keeps the 404 status code.

# wrong
ErrorDocument 404 https://example.com/errors/not-found.html
# right
ErrorDocument 404 /errors/not-found.html

3Verify

The response should now carry status 404 and your page body.

curl -i https://example.com/this-page-does-not-exist | head -n 1

Confirmed by httpd.apache.org

Did this fix it?

Cause 3 of 4

A text message with several words has no quotes

1Check

When the argument is neither a path nor a URL, Apache treats it as text. Text of more than one word must be wrapped in double quotes.

grep -n "ErrorDocument" .htaccess

2Fix

Quote the message, or point at a file instead.

ErrorDocument 404 "Sorry, that page does not exist"

3Verify

Test the config and request a missing URL.

sudo apachectl configtest
curl -i https://example.com/missing

Confirmed by httpd.apache.org

Did this fix it?

Cause 4 of 4

The request is proxied and the backend's own 404 wins

1Check

With mod_proxy, Apache passes the backend's error response through. Custom error pages for proxied content need ProxyErrorOverride.

grep -R -n "ProxyPass\|ProxyErrorOverride" /etc/httpd /etc/apache2 2>/dev/null

2Fix

Turn on ProxyErrorOverride for that virtual host, so Apache replaces the backend's error body with your ErrorDocument.

ProxyErrorOverride On
ErrorDocument 404 /errors/not-found.html

3Verify

Reload Apache and request a URL the backend answers with 404.

sudo apachectl configtest && sudo apachectl graceful
curl -i https://example.com/missing

Confirmed by httpd.apache.org

Did this fix it?

How do I stop it coming back?

  • Keep ErrorDocument in the virtual host file when you control the server, so .htaccess and AllowOverride do not matter.
  • Use a path that starts with a slash for 404 pages; never a full URL.
  • Run apachectl configtest before every reload.
  • After a change, request a missing URL with curl -i and read the status line, not only the page.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

Apache ignores your .htaccess file

500 Internal Server Error after editing .htaccess

Apache ignores .htaccess when AllowOverride is None, which is its default.

3 causes, each with a fix

Servers

dnf cannot install MySQL on Amazon Linux 2023

dnf cannot find a mysql-server package on Amazon Linux 2023

Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.