Custom Nginx Error Pages: 404, 403 & 5xx Guide

This guide shows you how to replace the default Nginx error pages with your own custom HTML pages for HTTP errors like 404 Not Found, 403 Forbidden, and 5xx server errors. You’ll learn to configure Nginx to serve branded, user-friendly pages that match your site’s design, improving user experience and providing helpful information when something goes wrong.

What You’ll Need

• A server or local machine with Nginx installed and running.
• Access to the Nginx configuration file (usually /etc/nginx/nginx.conf or a site-specific file in /etc/nginx/sites-available/).
• Root or sudo privileges to edit the configuration and restart Nginx.
• Text editor (e.g., nano, vim) and basic familiarity with the command line.
• Your custom HTML error pages (e.g., 404.html, 403.html, 500.html) with any associated CSS/images.

Step-by-Step

1. Create your custom error pages. Design HTML files for each error you want to customize. Place them in a directory accessible to Nginx, for example /usr/share/nginx/html/ or a custom path like /var/www/error/. Ensure the files are readable by the Nginx user (usually www-data or nginx).
2. Locate the Nginx configuration file. The main configuration is typically at /etc/nginx/nginx.conf. On Debian/Ubuntu, site-specific configs are in /etc/nginx/sites-available/ and symlinked to /etc/nginx/sites-enabled/. On CentOS/RHEL, look in /etc/nginx/conf.d/.
3. Edit the server block. Open the configuration file for your site (e.g., /etc/nginx/sites-available/example.com). Find the server { ... } block that handles your domain. If you want global error pages for all sites, you can add the directives to the http block in nginx.conf.
4. Add the error_page directives. Inside the server block, add lines like:

   error_page 404 /404.html;
   error_page 403 /403.html;
   error_page 500 502 503 504 /50x.html;

   The first part is the HTTP status code(s), the second is the URI that Nginx will redirect to when that error occurs. You can use a single page for multiple codes (as shown for 5xx).

5. Set the location for the error pages. If your error pages are in the default web root, you may not need a separate location block. However, if they’re in a different directory, define a location block to serve them:

   location = /404.html {
       root /var/www/error;
       internal;
   }

   The internal directive makes the page accessible only via Nginx’s internal redirect, not directly by users. This is a security best practice.

6. Test the configuration. Run nginx -t to check for syntax errors. It should output syntax is ok and test is successful.
7. Reload Nginx. Apply the changes by running systemctl reload nginx (or service nginx reload on older systems). This reloads the configuration without dropping connections.
8. Test your error pages. Trigger a 404 by visiting a non-existent URL (e.g., https://yourdomain.com/nonexistent). For 403, try accessing a directory with no index file and autoindex off. For 5xx, you can temporarily create a PHP script that throws an error, or use a simple test like ab -n 1 -m GET http://yourdomain.com/ after breaking something temporarily (but be careful).

Common Mistakes

• Forgetting the internal directive in the location block, which allows users to directly access your error pages (not a big deal, but less clean).
• Using absolute paths in error_page like /var/www/error/404.html instead of a URI. The directive expects a URI, not a file path.
• Not testing after reload – always run nginx -t before reloading to avoid breaking your site.
• Placing error pages outside the web root without a location block, causing 404 errors when Nginx tries to serve them.
• Overriding error pages for specific locations – if you have a location block with its own error_page, it will take precedence over the server-level one.

Tips

• Use a consistent design for all error pages to maintain brand identity.
• Include a link back to your homepage and a search box to help users navigate.
• For 5xx errors, consider adding a note like “Our team has been notifiedâ€� to reassure users.
• Use error_page 404 = @fallback; to redirect to a named location instead of a static file, if you need dynamic handling.
• If you use a CDN or proxy, you may need to configure error pages at that layer as well.
• Test on a staging environment before deploying to production.

Troubleshooting

• Changes not taking effect: Ensure you reloaded Nginx (nginx -s reload or systemctl reload nginx). If you edited a symlinked file, make sure you’re editing the actual file, not the symlink.
• Error pages show as 404: Check that the file exists and is readable by the Nginx user. Verify the root directive in the location block points to the correct directory.
• Still seeing default Nginx error page: Check if there’s a more specific error_page directive in a nested location block that overrides yours. Also, if you’re using a reverse proxy (like PHP-FPM), the backend might be generating its own error pages – you can use proxy_intercept_errors on; to catch them.
• Internal Server Error (500) when accessing error page: This usually means the error page file has a problem (e.g., PHP syntax error if you’re using PHP). Check the Nginx error log (/var/log/nginx/error.log) for details.
• Error page works but styles are missing: If your CSS/JS files are referenced with relative paths, they might break because the URL changes. Use absolute paths or set a base tag in the HTML.

Frequently Asked Questions

Can I use a single custom page for all errors?

Yes, you can set error_page 400 401 403 404 500 502 503 504 /error.html; to use one page for all specified codes. However, it’s often better to have distinct pages for user errors (4xx) and server errors (5xx) to provide appropriate messaging.

How do I redirect to an external URL for error pages?

Use a full URL in the error_page directive, like error_page 404 https://example.com/not-found.html;. But note that this causes a redirect (HTTP 302) rather than an internal subrequest, which may be less seamless.

What if I use a reverse proxy like Nginx with PHP-FPM?

By default, Nginx passes the error response from the backend directly to the client. To use your custom pages, add proxy_intercept_errors on; in the location block that proxies requests. Then the error_page directives will take effect.

Can I set different error pages for different domains?

Yes, just put the error_page directives inside the specific server block for that domain. Each server block can have its own error pages.

How do I test a 500 error page without breaking my site?

You can temporarily create a PHP file that throws an exception, or use a simple test like curl -I http://yourdomain.com/ after temporarily setting error_page 500 /50x.html; and then triggering a 500 by, for example, making a PHP script that calls trigger_error('test', E_USER_ERROR);. Remember to remove the test file afterward.

Does the internal directive affect SEO?

No, the internal directive only prevents direct access to the error page file. Search engines will still see the appropriate HTTP status code (404, 500, etc.) when crawling, which is correct. The error page content is not indexed separately.

Related

• Acer Collection S: Decline or Uninstall?
• C Drive Space Error: Fix ‘Not Enough Space to Extract
• Project Sekai EN Events: Current & Full Schedule