Tutorial · cloudflare · Published 2026-08-16 · 3 min read
Custom 5xx error pages on Cloudflare
Replace the default Cloudflare 5xx error pages with your own using Error Pages, custom error rules, and the diagnostic error tokens.
Two ways to customize
Cloudflare gives you two tools for replacing its default error pages, and they serve different needs.
- Error Pages (Caching and Performance or Custom domain pages): zone-level and, on paid plans, account-level templates that swap the visual look of the default 5xx and 1xxx pages while keeping Cloudflare's diagnostic box. This is the fastest option and requires no code.
- Custom error rules (Rules > Custom Errors): full control with a custom-filter expression that triggers on HTTP status codes 400 and above, serving your own asset or inline content. A matching custom error rule takes priority over an Error Page.
The user-facing error pages article covers the copy guidance that applies to both routes. This page focuses on the Cloudflare mechanics.
The error tokens
Both routes support tokens that Cloudflare replaces with real values right before serving the response. On a 5xx page you should keep the diagnostic ones, because they give your support team and Cloudflare the exact facts when you troubleshoot:
| Token | What it becomes |
|---|---|
::CLOUDFLARE_ERROR_500S_BOX:: | The standard 5xx diagnostic box (error code, ray ID) |
::CLOUDFLARE_ERROR_1000S_BOX:: | The standard 1xxx diagnostic box |
::RAY_ID:: | The unique request ray ID |
::CLIENT_IP:: | The visitor IP |
::GEO:: | The visitor country or region |
Keep ::CLOUDFLARE_ERROR_500S_BOX:: on a 5xx template: it is what lets you and Cloudflare support identify the exact failing request. Strip it and every 5xx looks identical to the user and to you.
Asset limits matter: a custom error asset fetched from a URL can be at most about 1.5 MB after Cloudflare inlines images, CSS and JS, and Cloudflare minifies content when it fetches an asset. An inline response is smaller still. Keep the page plain and the CSS minimal.
Build a custom error rule
- Prepare the page you want to serve, for example
/errors/500.htmlon an accessible URL, containing the error tokens you need. - Go to Rules > Custom errors (Cloudflare supports this on paid plans), create an asset from the URL.
- Create a custom error rule matching the 5xx class:
(http.response.code ge 500 and http.response.code le 599)- Attach the asset to the rule and set the response code (for example
530for all 5xx). - Deploy only after saving, and test with a forced 502 against a URL you control.
For a specific error, matching a single code is cleaner than a blanket: (http.response.code eq 502). For Cloudflare-generated 1xxx errors, match on cf.response.1xxx_code.
What the errors mean
The 502 vs 523 guide and the 521 guide walk each Cloudflare error code. For a custom page, keep those codes visible even when the storytelling changes.
Prevention
Keep every custom template in the zone's source (a branch on the same repo), re-upload the asset after every design change, and always retain the ::CLOUDFLARE_ERROR_500S_BOX:: token on a public 5xx page so a real incident still reports its ray ID.