Last Updated on April 20, 2021 by Amit

Apache ErrorDocument

ErrorDocument directive

ErrorDocument directive is part of Apache core module .

In this article you will learn how to use ErrorDocument in htaccess to manipulate your broken or forbidden URLs.

To use this directive in an htaccess file you do not need to do anything . This directive is enabled on Apache server by default.

ErrorDocument can be used in htaccess or server.config file on Apache server.

We use this to manipulate broken or blocked URLs on Apache.

ErrorDocument directive is used to add a custom URL or parh so that the server can redirect you to this path (the URL path or URL you set as destination in ErrorDocument) when you request a broken URL.

Table of contents

Uses of ErrorDocument

ErrorDocument is most often used to manipulate not-found 404 URLs on Apache server. You can use this directive to set your own custom page to handle 404 URIs on your website.

ErrorDocument syntex

This directive uses two required arguments
error code and destination :

ErrorDocument errorStatusCode destination

You can use any HTTP error status code starting from 4XX to 5XX ie: 403.

You can use URL path , full URL or Text as the destination string .

ErrorDocument 404 /error.php

ErrorDocument document is a one liner directive and both arguments should be in a single line otherwise you will get a 500 invalid syntex error if line break is found.

Using ErrorDocument to redirect 404 URLs to a custom path

If you want to set your custom own path for broken URLs on your server , you can the following:

ErrorDocument 404 /error.php

The above line tells server to serve error.php file when a not-found URI is requested.
Your server will internally map the requested URI to /error.php meaning that the typed URL won’t change in browser address bar.

ErrorDocument directive internally maps the request if you use a absolute URL path as its destination .
If you use a full URL starting with URL scheme then the directive will perform an external redirection changing the browser URL.

ErrorDocument 404 http://example.com/error.php

The above example will redirect your 404 URLs to http://example.com/error.php making the redirection visible to browser.

Using ErrorDocument to print a custom error text

With ErrorDocument directive it is also possible to show a custom error response text on the same page instead of sending the request to a different URL.
You can replace destination path with your “custom error text”.

See the following example:

ErrorDocument 404 "Oh.. thats a 404 error"

This will show a custom error text on the requested not-found page.

The text string must be enclosed with .

You can also use html tags to format your custom text.

ErrorDocument 404 "<h1>Oh.. thats a 404</h1>"

Using mod-rewite variables with ErrorDocument

mod-rewite (url rewriting ) variables like %{REQUEST_URI} can be used in the destination string of ErrorDocument .
This will help you track your broken pages.
Here is how you can use server variables with ErrorDocument

ErrorDocument 404 /error.php?page=%{REQUEST_URI}

This will rewrite a broken URI to error.php you can get the requested broken URI on your error.php page using the following code

echo $_GET["page"];

Please keep in mind that the above example will only work on Apache 2.4 or later versions . On earlier versions you will get the variables as is in your output.

Control 403 errors using ErrorDocument

You can use ErrorDocument to add custom error handler page for 403 errors on your site

ErrorDocument 403 /thispage.php

This will map all 403 forbidden requests to /thispage.php

ErrorDocument vs RewriteRule

RewriteRule directive takes precedence over ErrorDocument. If you have a RewriteRule that rewrites not-found requests to a specific file then your ErrorDocument won’t get triggered.

Let’s see an example:

ErrorDocument 404 /error.php

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule .* /error.php [L]

Both directives above handles a 404 request but unfortunately the ErrorDocument line isn’t read by server even if it at the top this is because RewriteRule runs before ErrorDocument on Apache server.

The simple workaround to overcome this type of problem is either use ErrorDocument or a RewriteRule to handle 404 URLs.


How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.