Nginx 400 Error Custom Page: Redirect Guide

When nginx returns a 400 Bad Request, visitors see a bare default error page that gives no context and can make your site look broken. This guide shows you how to replace that with a custom, branded error page—so users get a clear message and a way back to your site. You’ll need access to your nginx configuration file (usually nginx.conf or a site-specific file in sites-available) and the ability to reload nginx.

What You’ll Need

• Root or sudo access to the server running nginx.
• An HTML file for the custom error page (e.g., /var/www/html/400.html).
• A text editor (like nano or vim) to edit nginx config files.
• Basic familiarity with the command line.

Step-by-Step

1. Create your custom 400 error page. Write an HTML file with a helpful message and a link back to your homepage. For example, create /var/www/html/400.html with content like:

   <!DOCTYPE html>
   <html>
   <head><title>Bad Request</title></head>
   <body>
     <h1>400 - Bad Request</h1>
     <p>The request could not be understood by the server.</p>
     <p><a href="/">Go to homepage</a></p>
   </body>
   </html>

   Save the file and ensure it is readable by the nginx user (usually www-data).

2. Locate your nginx configuration. Run nginx -t to check the config file path, or look in /etc/nginx/. The main file is nginx.conf, but you’ll often edit a server block in sites-available/ (e.g., /etc/nginx/sites-available/default).
3. Open the server block. Use a text editor: sudo nano /etc/nginx/sites-available/default (adjust the path to your setup).
4. Add the error_page directive. Inside the server { ... } block, add a line like:

   error_page 400 /400.html;

   This tells nginx to serve /400.html when a 400 error occurs. If your custom page is in a different location, use a URI that maps to it (e.g., error_page 400 /custom_errors/400.html;).

5. Make sure the location is accessible. If the page is not in the root directory, you may need to add a location block to serve it. For example, if your root is /var/www/html and the file is /var/www/html/400.html, the URI /400.html works automatically. For a subdirectory, add:

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

   The internal directive prevents direct access to the error page (only nginx can serve it).

6. Test the configuration. Run sudo nginx -t to check for syntax errors. If it says “syntax is okâ€� and “test is successful,â€� proceed.
7. Reload nginx. Apply the changes with sudo systemctl reload nginx (or sudo nginx -s reload). No downtime is needed.
8. Verify it works. Trigger a 400 error by sending a malformed request. For example, using curl: curl -i -X TRACE http://yourdomain.com/ (or any method that nginx rejects). You should see your custom page instead of the default nginx error.

Common Mistakes

• Forgetting the internal directive. Without it, users can directly access /400.html, which is fine but not ideal. More importantly, if the page is missing, nginx will return a 404 for the error page, causing a loop.
• Using a full URL in error_page. The directive expects a URI, not a URL. Use /400.html, not http://example.com/400.html.
• Not testing after editing. A typo in the config can break nginx entirely. Always run nginx -t before reloading.
• Placing the directive in the wrong block. If you have multiple server blocks, make sure you edit the one that handles the traffic you’re testing. Use server_name to identify it.
• File permissions. If nginx cannot read the HTML file, it will return a 403 or 500. Ensure the file is readable by the nginx user (e.g., sudo chmod 644 /var/www/html/400.html).

Tips

• Use a single error page for multiple codes. You can specify multiple codes: error_page 400 404 500 /error.html; but then you need to handle them differently if you want distinct messages.
• Include a link back to your homepage. A lost user is more likely to stay if they can navigate back easily.
• Keep the page small. Error pages should load quickly, so avoid large images or scripts.
• Log the error. Use error_page 400 = @error_400; with a named location if you want to log the error or perform additional processing. But for simple redirects, the basic directive is enough.
• Test with different request methods. A 400 can be triggered by malformed headers, invalid HTTP versions, or bad request lines. Use curl with --http1.0 or a raw socket to simulate.

Troubleshooting

If your custom page doesn’t appear, try these steps:

• Check nginx error logs. Look in /var/log/nginx/error.log for messages like “directory index of … is forbiddenâ€� or “open() … failedâ€�. This will tell you if the file is missing or unreadable.
• Verify the error code. Use curl -i to see the actual HTTP status. If you get a 404 instead of 400, your request isn’t triggering the error you think.
• Make sure the error_page directive is in the correct server block. If you have multiple sites, the wrong block may be handling the request. Use nginx -T to dump the full config and check which server block matches your domain.
• Clear your browser cache. Your browser might be showing a cached version of the old error page.
• Try a different URI. If you use a subdirectory, ensure the location block is defined correctly. A common mistake is using alias instead of root.
• If you get a 500 Internal Server Error, it often means the error page file itself is not accessible. Check permissions and the path in the root directive.

Frequently Asked Questions

Can I redirect to an external URL for a 400 error?

Yes, you can use a full URL in the error_page directive, but nginx will issue an HTTP redirect (302) to that URL. This is not recommended because it changes the status code and may confuse users or SEO. Better to serve a local page.

Will this affect SEO?

No, a 400 error is a client error, and serving a custom page doesn’t change the HTTP status code. The response code remains 400, which is correct. Search engines will still see it as a bad request.

Can I use a PHP file as the error page?

Yes, you can. Just make sure the location block includes fastcgi_pass or include fastcgi_params; to process PHP. However, for error pages, a static HTML file is simpler and more reliable.

How do I test a 400 error if I don’t know how to trigger one?

You can use curl with a malformed request, like curl -i -X FOO http://example.com/ (an invalid method). Or use curl --http1.0 --request-target "*" http://example.com/ to send an invalid request target.

What if I have multiple server blocks? Do I need to add the directive to each?

Yes, each server block that should use the custom error page needs its own error_page directive. You can also place it in the http block to apply globally, but then all sites will use the same page.

Is there a way to redirect only for certain types of 400 errors?

No, nginx doesn’t distinguish between different causes of a 400 error. The directive applies to all 400 responses. If you need different handling, you’d have to use a more complex setup with error_page and named locations, but that’s rarely necessary.

Related

• World’s Fastest microSD Card: What “Fastest” Means
• Four-Marketplace AI Listing Optimizer Architecture
• Claude for Startups Alternatives: Coding AI and Credits