Error pages

ConceptsCopy Anchor Link

Set a site's error pagesCopy Anchor Link

1. Open Sites, select the site, and go to the Error pages tab.

2. Enter an HTML template in the field of a status; statuses left empty use the built-in page. To redirect instead, choose Redirect to URL above the status and enter the URL; a template page can change the status it is sent with in Response status.

3. To replace errors the origin returns itself, turn on Replace origin error responses.

4. Click Save. The console publishes a revision ("Error pages of {site} updated"); nodes hot-update without a reload.

5. Verify:

   Copy Text

   curl -s -D - -H 'Host: www.example.com' http://<node IP>/<a path a rule denies>

   The answer is 403 with Content-Type: text/html; charset=utf-8, Cache-Control: no-store and the template.

Redirect pagesCopy Anchor Link

With Redirect to URL, responses of that status become a 302 redirect.

Maintenance modeCopy Anchor Link

In the Maintenance mode card on the Error pages tab, turn on Enabled, fill in Retry-After (seconds), Allowed addresses, Allowed path prefixes and Maintenance page as needed, and click Save. The other settings are kept while it is off.

TemplatesCopy Anchor Link

Example:

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>{{status}}</title>
<h1>We could not complete your request</h1>
<p>Request ID: {{request_id}}</p>
<p>{{time}} · {{path}}</p>

Built-in pagesCopy Anchor Link

Without a template, nodes answer with a self-contained built-in page: no external resources, no script, light or dark with the system. The page shows the status and the path from the visitor through the edge node to the origin, marking the hop that failed (the visitor, the edge node or the origin) and its state; below come the title, what the visitor can do, Reload where reloading can help, and the request ID, the time the node answered (UTC), the host and the visitor's IP (shown on click). Motion is CSS only and stops when the system asks for reduced motion. The language is Chinese or English, whichever ranks highest in Accept-Language; English when neither is listed.

Requests the node refuses and the node's internal errors use the site's pages in the lookup order when the site is known, else the built-in page. A refused request marks the visitor on the path, an internal error the edge node:

Platform error pagesCopy Anchor Link

Set them under System settings → Platform error pages, with the rules of site templates; empty fields use the built-in page. Saving publishes a revision for every cluster ("Platform error pages updated") and is audited as system.error_pages_update, see System settings.

Nodes recognize disabled sites from the offline host list in their configuration (the domains of disabled sites); wildcards match as site domains do. Once the site is enabled again, the host is served again; once the site is deleted or the domain removed from it, the host is no offline host any more and answers 404. Both pages are for HTTP requests only: nodes complete no TLS handshake for these hosts, so HTTPS requests fail in the handshake.

Request IDsCopy Anchor Link

Node requirementsCopy Anchor Link

TroubleshootingCopy Anchor Link