How do I customize Cloudflare error pages?

Cloudflare has a wide range of error codes that allow us to differentiate specific problems. By default, these error pages mention Cloudflare; however, as a paying customer you can customize and brand these error pages. Having custom error pages allows to provide a consistent experience for your users, even in the event of a page load error.

The customizable error pages are broken into two groups:

Challenges:

Basic security

Web Application Firewall

IP Firewall (Country block, Country challenge, IP (range) block)

Cloudflare errors:

502, 504, and CF 52X errors

10XX errors

Always Online

NOTE:500, 501, 503, and 505 responses will not trigger custom error pages to avoid breaking specific API endpoints and other web applications. Custom error pages should be reserved for cases where the origin server can not return a response for the request (520-526 errors).

Customizing your error pagesBelow is a basic, custom error template, which you can build on. When creating your custom error templates, please note that the maximum page size is 1.5 MB and the page cannot be blank. Additionally, all external resources are inlined using base64 encoding, making them approximately 50% larger when published.

Available custom error tokensSome types of custom error pages must include one of the below tokens anywhere within the HTML of the custom error page. Only one page specific token may be present per error page, so if you wish to customize every error you will need to create one custom error page for each error containing the respective token.

Page Type

Token

All pages

::CLIENT_IP::

All pages

::RAY_ID::

Basic Security (CAPTCHA Challenge)

::CAPTCHA_BOX::

WAF (CAPTCHA Challenge)

::CAPTCHA_BOX::

Country Challenge (CAPTCHA Challenge)

::CAPTCHA_BOX::

I'm Under Attack Mode (Interstitial Page)

::IM_UNDER_ATTACK_BOX::

5XX Errors

::CLOUDFLARE_ERROR_500S_BOX::

1XXX Errors

::CLOUDFLARE_ERROR_1000S_BOX::

Always Online

::ALWAYS_ONLINE_NO_COPY_BOX::

StylingEach tag has a unique class that you can use to style individual error codes. It is possible to use CSS to stylize the tags in the div/span/section since they all have class IDs. Please note that each page (challenge, 5xx errors) will use a different ID, so you should use the preview option to get the proper ID.

PublishingOnce you're done customizing your error pages, you will need to publish them to our edge. This can be done by pressing the "Customize" button next to each customizable error. Once you press the "Customize" button you will be presented with a pop-up asking you for the URL to your custom error page.

When you entered the URL to your custom error page and hit the "Publish" button the custom error page will be requested once by us, and then stored on our servers.

UpdatingError pages can be updated by re-publishing them. Note that because of this if Cloudflare cannot load your site or you have blocked the US in the Cloudflare firewall, publishing and previewing the error page will not work.

Troubleshooting issues with custom error pages

If you encounter errors while attempting to preview or publish your custom error page, run it through a HTML validator and ensure that it is error free.

Make sure that the minimum page size is greater than 0. You will need to add content to your page.

Make sure that you are serving the custom error page with a 200 status code.

If Cloudflare cannot load your site or you have blocked the US in the IP Firewall, publishing and previewing the error page will not work.