Use Nginx’s error_page directive to map an existing HTTP 400 response to an HTML file or another URI. For a locally generated error page, define the mapping in the server block that handles the request, serve the file from an internal location, and use the equals form when the response must remain status 400:
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
server {
listen 80;
server_name example.com;
error_page 400 = /custom-400.html;
location = /custom-400.html {
root /var/www/errors;
internal;
}
}That configuration serves /var/www/errors/custom-400.html through Nginx’s error flow while preserving the original 400 status. If the 400 came from an upstream application, enable proxy_intercept_errors on; in the proxied location as well.
As an Amazon Associate I earn from qualifying purchases.
Free tools Windows power users keep installed
One-click scans. No signup required.
What error_page does—and what it does not do
error_page handles an error status that already exists. It does not create a 400 response by itself. Nginx’s official guide describes the directive as a way to return a custom page with an error code, substitute another response code, or redirect the browser to a different URI.
A deliberate test or an application rule must generate the status first. In a temporary test location, return 400; creates the response; Nginx then applies the matching error_page 400 ... rule.
#1 Best Overall
location = /test-bad-request {
return 400;
}Keep a test rule isolated and remove it after verification. A real malformed request, an upstream response, and a parser-level protocol failure can enter different Nginx paths, so a successful deliberate test does not prove that every possible 400 will use the same page.
Choose between an internal page and a client-visible redirect
There are two different outcomes often described as “redirecting” a 400. Decide which one you need before writing the directive.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11| Goal | Configuration form | What the client receives |
|---|---|---|
| Serve a local custom document and keep the error status | error_page 400 = /custom-400.html; |
The custom content is returned with status 400. |
| Serve a local document through Nginx’s internal error flow | error_page 400 /custom-400.html; |
Nginx internally redirects to the URI; without an explicit replacement status, the response commonly becomes the page’s normal success response. |
| Send the browser to another URL | error_page 400 =302 https://example.com/bad-request; |
The client receives a 302 response and then makes a new request to the absolute URL. |
The equals-status form lets you preserve or replace the response code. Use = /custom-400.html when monitoring, API clients, and browser tooling must continue to see 400. Use an explicit 3xx such as =302 only when a browser-visible redirect is genuinely desired. A redirect is a new request, so it is not the same as displaying a local error document while retaining the original failure status.
Method handling during an internal error redirect
For an internal URI error page, Nginx changes request methods other than GET and HEAD to GET when it performs the redirect. This is normally appropriate for a static HTML explanation, but it matters if the target URI is handled by application code that expects the original method or request body. A named location can be used when you need more controlled internal handling rather than a simple document URI.
Build a local custom 400 page
The following setup keeps the error document on the same virtual host and prevents visitors from requesting the file as an ordinary public endpoint.
Rank #2
1. Create the document under the configured root
With root /var/www/errors; and the URI /custom-400.html, Nginx looks for:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
/var/www/errors/custom-400.htmlThe file must exist and be readable by the Nginx worker. Give the page a useful explanation and a recovery path, such as checking the URL or returning to the site’s main entry point. Avoid exposing request details that could contain credentials or other sensitive data.
2. Add the mapping and an exact internal location
server {
listen 80;
server_name example.com;
error_page 400 = /custom-400.html;
location = /custom-400.html {
root /var/www/errors;
internal;
}
}The exact-match location (location =) ensures that this one URI receives the intended file settings. The internal directive allows Nginx to use the URI for error handling while rejecting a direct client request to that path. This prevents the custom document from becoming a normal public route while still allowing error_page to invoke it.
3. Validate and reload
- Run
nginx -tto check the syntax and referenced configuration. - Reload Nginx after the test succeeds so workers receive the updated configuration.
- Trigger a controlled
return 400;rule or another known application-level 400 and inspect both the response status and the displayed body.
If the page is shown but the status is 200, change the mapping to error_page 400 = /custom-400.html;. If the page is not found, verify the relationship between the URI and the root path: Nginx appends the URI to the configured root.
Handle 400 responses from a reverse proxy
When a backend application returns 400, Nginx normally passes that upstream response through to the client. To route qualifying upstream errors through Nginx’s error_page processing, turn on interception in the proxied location.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →server {
listen 80;
server_name example.com;
error_page 400 = /custom-400.html;
location / {
proxy_pass http://backend;
proxy_intercept_errors on;
}
location = /custom-400.html {
root /var/www/errors;
internal;
}
}proxy_intercept_errors on; tells Nginx to intercept proxied responses with status 300 or greater and process them using the configured error handling. Without it, a backend-generated 400 is returned as the backend produced it, so the local custom page will not appear even though the error_page directive is present.
Prevent an error-page loop
Make sure the custom URI is served locally and is not sent back to the backend. The exact internal location above is important: it takes precedence over the broad location / proxy, and its root serves the file directly. If the error URI is accidentally proxied, the backend can generate another 400, causing repeated interception or an unexpected response instead of the document.
Distinguish backend errors from Nginx parser errors
Interception applies to responses received from the proxied server. It cannot retroactively intercept a request that Nginx rejected while parsing the request line, headers, TLS handshake, or protocol. Those failures must be tested separately.
Put the directive in the server block that actually handles the request
Nginx applies error handling using the error_page directive in the server currently fulfilling the request. Defining the rule in an unrelated virtual host has no effect.
Separate HTTP and HTTPS virtual hosts
If HTTP and HTTPS use separate server blocks, configure the mapping in each block where the custom page is required. Testing only port 80 does not verify the listener on port 443.
Requests with an invalid or unexpected Host header
A request whose Host header does not match the expected names can be handled by a default server. In that case, the default server’s error_page settings govern the response, not the block you intended for the normal hostname. Check which virtual server receives the request before changing the page configuration.
Location-level rules and broad proxies
A broad proxied location can hide a static error URI if the URI is not given its own exact location. Keep the custom page location explicit, local, and non-proxied. Then place the 400 mapping where the relevant server’s normal and proxy locations can use it consistently.
Why some 400 errors do not use the page you expect
Nginx has parser-level and protocol-specific 400 paths in addition to an ordinary application or location error. The Nginx source identifies specialized conditions that are rendered to clients as 400-class responses:
- 494: request-header or cookie size exceeded; this is rendered as a 400 response.
- 495 and 496: TLS certificate errors; these are rendered as 400 responses.
- 497: plain HTTP sent to a port configured for HTTPS; this is rendered as a 400 response.
These conditions can occur before ordinary location processing. Consequently, a test endpoint containing return 400; exercises the normal error-page path but may not reproduce a header-size failure, a client-certificate problem, or an HTTP-to-HTTPS protocol mistake. Verify the exact failure mode and test the listener where it occurs.
A practical troubleshooting sequence
- Check syntax: run
nginx -t. Correct syntax errors before reloading. - Reload the active configuration: an edited file has no effect until Nginx reloads successfully.
- Verify the file path: confirm that the configured root contains
custom-400.htmland that the Nginx worker can read it. - Confirm the URI is local: make sure the custom-page location is not being sent to the upstream proxy.
- Intercept upstream statuses: add
proxy_intercept_errors on;in the location that calls the backend when the backend is the source of the 400. - Identify the serving server: check HTTP versus HTTPS, the requested port, the hostname, and default-server behavior for invalid Host headers.
- Test two classes of failure: first use a controlled
return 400;, then reproduce the actual failing request. A parser-level 400 variant can follow a different path. - Check the status separately from the body: a branded page can be displayed while the response has unintentionally changed from 400 to a success code or to a 3xx redirect.
Common configuration mistakes
Assuming error_page generates the error
A mapping remains idle until Nginx or an upstream actually returns the configured status. Add a temporary return 400; rule for a controlled check, or reproduce the application condition that creates the error.
Forgetting the equals form
error_page 400 /custom-400.html; and error_page 400 = /custom-400.html; are not equivalent when status preservation matters. The second form explicitly keeps the original 400 status while serving the custom URI.
Using an external redirect when an error status must remain visible
A directive such as error_page 400 =302 https://example.com/bad-request; intentionally returns a redirect. The client then requests the destination separately. Use this only when that browser-visible navigation is the desired behavior; use the internal URI form for a local error document.
Recommended Free Tools
Testing only a backend-generated error
With proxy interception disabled, the backend’s 400 bypasses the local page. Turn interception on in the proxied location and ensure the custom URI itself is not proxied.
Testing only one listener
HTTP, HTTPS, and default-server traffic can be fulfilled by different server blocks. A working page on one listener does not establish that the other block has the same mapping.
Decide which implementation fits your application
| Situation | Recommended pattern | Reason |
|---|---|---|
| Nginx or a local rule creates the 400, and clients should retain the error status | Server-level error_page 400 = /custom-400.html; with an internal static location |
Displays local content without converting the response into a normal success page. |
| A backend creates the 400, and the same branded page should be used | Add proxy_intercept_errors on; to the proxied location, then use the same error mapping |
Allows Nginx to process the upstream status through error_page. |
| The browser must leave the current host | Use an explicit external status such as error_page 400 =302 https://example.com/bad-request; |
Returns a client-visible redirect rather than an internal document. |
| The failure involves oversized headers, TLS certificates, or HTTP on an HTTPS port | Test and diagnose the relevant listener and parser condition separately | These specialized 400 paths can occur before ordinary location processing. |
Final configuration checklist
- The mapping is in the server that fulfills the request.
- The custom file exists beneath the configured
root. - The custom-page location is marked
internal. - The custom URI is not accidentally proxied.
=is present when the response must remain status 400.proxy_intercept_errors on;is present when the backend generates the 400.- The configuration passes
nginx -tand has been reloaded. - Both a deliberate 400 and the real failure mode have been tested.
Frequently Asked Questions
Why does my custom page appear with a 200 status instead of 400?
Use error_page 400 = /custom-400.html;. The equals form explicitly preserves the original 400 while serving the custom document.
Why does the page work for return 400; but not for my reverse-proxy error?
Enable proxy_intercept_errors on; in the proxied location. Without interception, Nginx passes the upstream 400 directly to the client.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Can I request the internal error page directly?
The internal directive is intended to allow Nginx’s error handling to use the URI while preventing ordinary external requests to that path.
Why are some 400 responses still using Nginx’s default page?
Header or cookie size failures, TLS certificate errors, and plain HTTP sent to an HTTPS port can be parser-level or protocol-specific conditions that occur before normal location processing. Test the exact failure and the server block handling that listener.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
