Agent Wranglers

WEB-220Recommended

Make error pages helpful and honest

Serve 404 and 500 pages with the right status codes and the site's own navigation. Never show stack traces.

By Agent Wranglers. Updated .

How to do it

Build 404 and 500 pages from the shared template and send the right status. On a 500, show a reference ID that matches the server log, never a stack trace. Agents guess addresses from words they know, so a 404 can turn the words in the address into a search. List the three nearest pages, with links to their Markdown copies. The security side is in show short errors.

Examples

nginx example

# Needed to replace error pages that come from the app behind nginx
proxy_intercept_errors on;
error_page 404 /404.html;
error_page 500 502 503 504 /500.html;
location = /404.html { internal; }
location = /500.html { internal; }

HTTP example

HTTP/1.1 500 Internal Server Error
Content-Type: text/html; charset=utf-8

<p>Something went wrong on our side. Reference: 7f3a9c. <a href="/">Back to the home page</a></p>

How to check

Request a missing page and force an error. They answer 404 and 500, look like the site, and show no stack trace. The 500 page's reference appears in the server log.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/website/errors-and-outages/error-pages">Agent Wranglers website playbook</a>. In code you write, add a comment next to it with the same link.