NGINX Custom Error Pages & Fallback Prompt
Design clean custom error pages and graceful fallbacks in NGINX — branded 404/50x pages, an upstream-down maintenance page, and error interception that doesn't leak backend errors or break API JSON responses.
- Target user
- Engineers building branded error and maintenance handling in NGINX
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior web engineer who designs error and maintenance handling in NGINX. You make failures look intentional and branded without hiding real problems from operators or corrupting API responses.
I will provide:
- My current `server` block and where static assets live: [PASTE CONFIG]
- Which routes are browser HTML vs API/JSON: [DESCRIBE]
- The error states I want to handle (404, 500/502/503/504, upstream down, maintenance): [LIST]
- Whether I have a reverse-proxied upstream (so upstream errors need interception): [YES/NO]
- Any branding/asset constraints for the pages (self-contained, CDN paths): [DESCRIBE]
Design the handling:
1. **Custom pages** — `error_page` directives mapping status codes to internal locations serving static HTML (e.g. `error_page 404 /404.html;` with a matching `location = /404.html { internal; }`). Keep the pages self-contained so they render even when the app is down.
2. **Upstream error interception** — for proxied HTML routes, `proxy_intercept_errors on` so a backend 502/503 shows your branded page, not the raw upstream error. Explain the tradeoff and scope it away from API routes.
3. **Protect API responses** — for JSON/API `location`s, DO NOT intercept upstream errors; let the structured error body pass through so clients can parse it. Show the split explicitly.
4. **Maintenance mode** — a toggle (a flag file with `if (-f ...)` or a `map`) that returns `503` with a `Retry-After` header and a static maintenance page for humans, while optionally allowing an allow-listed admin IP through.
5. **Preserve status codes** — ensure the response keeps the real status (404 stays 404, 503 stays 503) so monitoring, caches, and SEO see the truth; never mask a 500 as a 200.
Output: (a) the full `server`/`location` config, commented, with the HTML-vs-API split; (b) a minimal self-contained 404 and 50x HTML template; (c) the exact command to enter/exit maintenance mode; (d) `curl -I` checks confirming each route returns the right status and page; (e) `nginx -t` verification. Apply only after `nginx -t` passes and reload.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
Custom error pages are easy until a reverse proxy is involved. proxy_intercept_errors on is what turns a raw upstream 502 into your branded page — but the same switch will overwrite the JSON error body your API clients depend on. The prompt forces an explicit HTML-vs-API route split so interception improves the human experience without corrupting machine responses.
Maintenance mode is the other common trap: teams return a friendly page but accidentally serve it as a 200, which tells caches, uptime monitors, and search engines that everything is fine. Requiring a real 503 plus Retry-After (and an admin IP allow-list) keeps the page human-friendly while staying honest to every automated system watching.
The curl -I verification step confirms the two things that actually matter — the right status code and the right body — for both a browser route and an API route, so you know the split works before real failures test it.
Related prompts
-
NGINX Canary & Blue-Green Routing Prompt
Design percentage-based canary and blue-green traffic routing in NGINX using split_clients and upstream weighting — with a sticky cohort, an instant rollback path, and a way to force yourself onto the canary for testing.
-
NGINX CORS & Preflight Proxy Prompt
Get correct, secure CORS handling in NGINX for a reverse-proxied API — OPTIONS preflight, Access-Control-* headers, credentials, and per-origin allow-listing — without the classic duplicate-header and wildcard-with-credentials footguns.
-
NGINX GeoIP2 Country Access Control Prompt
Add country- or ASN-based access control and routing to NGINX with the ngx_http_geoip2 module — allow/deny by country, route regional traffic, and set headers — while correctly resolving the real client IP behind a CDN or load balancer.
-
NGINX Zero-Downtime Reload & Binary Upgrade Prompt
Apply NGINX config and binary changes with zero dropped connections — safe reload workflow, graceful worker draining, on-the-fly binary upgrades with USR2/QUIT, and a rollback plan when a reload goes wrong.
More NGINX prompts & error guides
Browse every NGINX prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.