Customizing Cloudflare error pages

Learn how to customize Cloudflare's default error pages to better fit your brand and messaging.


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 (using the Pro, Business, or Enterprise plan) 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.

After all linked assets (CSS, JS, base64 encoded images, etc) are inlined, the size of a custom error page cannot exceed 1.43MB.

The customizable error pages are broken into two groups:


  • Basic security
  • Web Application Firewall
  • IP Firewall (Country block, Country challenge, IP (range) block)

Cloudflare errors:

  • 502, 504, and CF 52X errors
  • 1XXX errors
  • Always Online
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 pages

Below is a basic, custom error template, which you can build on. When creating your custom error templates, the page cannot be blank. Additionally, all external resources are inlined using base64 encoding, making them approximately 50% larger when published.

::[REPLACE WITH TOKEN NAME]:: </body> </html>


Available custom error tokens
Some 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::
Country Challenge (CAPTCHA Challenge) ::CAPTCHA_BOX::
I'm Under Attack Mode (Interstitial Page) ::IM_UNDER_ATTACK_BOX::

Each 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.

Once 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.

Error 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

Error 1005 (blocked IP) is customized via IP/Country Block, not 1XXX Errors

1XXX Errors do not customize the following HTTP errors:

  • 1001 - Unable to resolve
  • 1003 - Bad Host header
  • 1014 - Cross CNAME ban
  • 1016 - Origin DNS error
  • 1018 - Unable to resolve because of ownership lookup failure
  • 1023 - Unable to resolve because of feature lookup failure
  • 1200 - Cache Connection Limit

General troubleshooting advice:

  • 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.
Not finding what you need?

95% of questions can be answered using the search tool. This is the quickest way to get a response.

Powered by Zendesk