Custom error pages

Overview

This article explains how to redirect server errors to custom error pages on your website.

Custom error pages enable you to customize the pages that display when an error occurs. This makes your website appear more professional and also prevents visitors from leaving your site.

If a visitor sees a generic error page, they are likely to leave your site. However, if they see a helpful error page, they are more likely to stay because they are able to simply click a link to go to another page within your site.

Apache

The following instructions are for an Apache server. If your server is running Nginx, see the section at the bottom titled Creating custom error pages with Nginx.

500 errors on an Apache server

It is not possible to redirect to a custom 500 error page due to how DreamHost Apache servers are configured. When a 500 error is encountered, the default browser 500 page always displays.

Simple example

Log into your server via SSH.
Navigate to your website directory.
Create a file named .htaccess.
Add the following line to your site's .htaccess file:
```
ErrorDocument 404 /error.php
```

This single line redirects browsers that experience a 404 error (Not Found) to the file error.php located in the same directory as your site's .htaccess file.

You can use the above line as a template to create separate custom error pages for each error code.

Status codes

The complete list of errors is available here:

Status codes

The list of status codes is very long, but there are only a few common errors you'll probably want to make entries for, including:

400 – Bad Request
401 – Unauthorized
403 – Forbidden
404 – Not Found

For example, to catch those errors, you would add the following to your .htaccess file for the domain you'd like to configure:

ErrorDocument 400 /error.php
ErrorDocument 401 /error.php
ErrorDocument 403 /error.php
ErrorDocument 404 /error.php

These lines force a browser to redirect to the /error.php file if it encounters any of the status codes above.

Example of an error.php file

The following code is an example of what you could add to an error.php file. This example is written in PHP, but you can use any language you like.

You can then add CSS styles to the page so that it blends into the rest of your website:

<?php

$page_redirected_from = $_SERVER['REQUEST_URI'];  // this is especially useful with error 404 to indicate the missing page.
$server_url = "http://" . $_SERVER["SERVER_NAME"];
$redirect_url = $_SERVER["REDIRECT_URL"];
$redirect_url_array = parse_url($redirect_url);
$end_of_path = strrchr($redirect_url_array["path"], "/");

switch(getenv("REDIRECT_STATUS"))
{
    # "400 - Bad Request"
    case 400:
    $error_code = "400 - Bad Request";
    $explanation = "The syntax of the URL submitted by your browser could not be understood. Please    verify the address and try again.";
    $redirect_to = "";
    break;

    # "401 - Unauthorized"
    case 401:
    $error_code = "401 - Unauthorized";
    $explanation = "This section requires a password or is otherwise protected. If you feel you have reached this page in error, please return to the login page and try again, or contact the webmaster if you continue to have problems.";
    $redirect_to = "";
    break;

    # "403 - Forbidden"
    case 403:
    $error_code = "403 - Forbidden";
    $explanation = "This section requires a password or is otherwise protected. If you feel you have reached this page in error, please return to the login page and try again, or contact the webmaster if you continue to have problems.";
    $redirect_to = "";
    break;

    # "404 - Not Found"
    case 404:
    $error_code = "404 - Not Found";
    $explanation = "The requested resource '" . $page_redirected_from . "' could not be found on this server. Please verify the address and try again.";
    $redirect_to = $server_url . $end_of_path;
    break;
}
?>

<!DOCTYPE html>
<head>
  <link rel="Shortcut Icon" href="/favicon.ico" type="image/x-icon" />
<?php
    if ($redirect_to != "")
    {
?>

<meta http-equiv="Refresh" content="5; url='<?php print($redirect_to); ?>'">
<?php
    }
?>
<title>Page not found: <?php print ($redirect_to); ?></title>

</head>
<body>

<h1>Error Code <?php print ($error_code); ?></h1>

<p><?PHP echo($explanation); ?></p>

<hr />

<p><i>A project of <a href="<?php print ($server_url); ?>"><?php print ($server_url); ?></a>.</i></p>

</body>
</html>

Nginx

Creating custom error pages with Nginx

The following steps walk you through creating custom error pages on an Nginx server.

Note that configuration files for Nginx sites go into a special directory under your username. View the following article for further details on where to place your config file:

Nginx configuration file locations

Log into your server via SSH.
Navigate into the following directory.

Make sure to change username to your Shell user and example.com to your website:
```
[server]$ cd /home/username/nginx/example.com
```
Create a file named error.conf in this directory with the following code:
```
error_page 404 /404.html;
location  /404.html {
  internal;
}
```
Navigate to your site directory. For example:
```
[server]$ cd ~/example.com
```
Create a page titled 404.html with any error message you wish to display.
Reboot your server (if on a VPS). If on Dedicated, you can reload Nginx yourself.

When you now visit a page on your site that does not exist, your custom error page displays.

Overview

Apache

500 errors on an Apache server

Simple example

Status codes

Example of an error.php file

Nginx

Creating custom error pages with Nginx

See also

Internal links

External links

Still not finding what you're looking for?

Status Updates

DreamHost Academy

Blog & News