How do I customize Cloudflare error pages?

Table of Contents

  1. Overview
  2. Customizing your error pages
    1. Available custom error tokens
    2. Styling
    3. Publishing
    4. Updating
  3. Troubleshooting issues with custom error pages

Overview

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 pages
Below 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.

<html>
<head></head>
<body>
<p>::ERROR_TOKEN::</p>
</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 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.

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::

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

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

Updating
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

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

The Cloudflare team is here to help. 95% of questions can be answered using the search tool, but if you can’t find what you need, submit a support request.

Powered by Zendesk