Configuring Custom Pages (Error and Challenge)

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


Overview

Cloudflare uses a wide range of error codes to identify issues in handling request traffic. By default, these error pages mention Cloudflare; however, custom error pages help you provide a consistent brand experience for your users. 

If you are on the Pro, Business, or Enterprise plan you can customize and brand these pages for your whole account or for specific domains. You can design custom error pages to appear during a security challenge or when an error occurs.

500, 501, 503, and 505 responses do not trigger custom error pages to avoid breaking specific API endpoints and other web applications.

Alternatively, Enterprise customers can customize 5XX error pages at their origin via Enable Origin Error Pages in the Custom Pages app in the dashboard..

Enable Origin Error Pages excludes 521 and 522 errors.


Step 1: Create a custom page

Before adding a custom error page to your Cloudflare account, you will need to design, code, and host that page on your own web server.

You can use the following custom error template to start building your page:

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

Your custom error page must include a custom error token and cannot exceed 1.43 MB.

When published, any additional scripts, images, or stylesheets increase the size of your custom error page source by approximately 50%. Download the collapsify tool to test your page size before publishing.

Custom Page example

Here is sample code for a custom 500 class error page without styling: 

<!DOCTYPE html>
<html>
 <head>
   <meta charset="utf-8">
    <title>500 Level Errors page</title>
</head>
<body>
  <h1> 500 Level Errors </h1>
  <h2>::CLOUDFLARE_ERROR_500S_BOX::</h2>
</body>
</html>


Step 2: Select your custom error tokens

When designing your custom error page, you must include one page-specific custom error token.  Each custom error token provides diagnostic information that appears on the error page. 

To display a custom page for each error, create a separate page per error. For example, to create a custom error page for both IP/Country Block and WAF (Captcha Challenge), you must design and publish two separate pages. 

The following tables list each custom error token grouped by the applicable custom error page.

Token Available to

::CLIENT_IP::

All pages

::RAY_ID::

All pages

Only one page-specific custom error token can be used per page.

Token Available to

::GEO::

IP/Country Block

::CAPTCHA_BOX::

  • Basic Security (CAPTCHA Challenge)
  • WAF (CAPTCHA Challenge)
  • Country Challenge (CAPTCHA Challenge)

::IM_UNDER_ATTACK_BOX::

I'm Under Attack Mode (Interstitial Page)

::CLOUDFLARE_ERROR_500S_BOX::

5XX Errors

::CLOUDFLARE_ERROR_1000S_BOX::

1XXX Errors

::ALWAYS_ONLINE_NO_COPY_BOX::

Always Online


Step 3: Style your custom page

Each custom error token has a default look and feel. However, you can use CSS to stylize each custom error tag using each tag's class ID. 

If you are familiar with CSS styling, you can customize the look and feel of the error page using each tag’s class ID.


Step 4: Publish your custom page

After customizing your custom error page, there are two options for adding the page to Cloudflare:

  • Account level: the custom error page will apply to every domain associated with your account.
  • Domain level: the custom error page will apply to only one domain associated with your account.

If Cloudflare cannot load your site or you have blocked the United States (US) via IP Access Rules or Firewall Rules, publishing and previewing the error page will not work.

Account-level custom error page

To publish an account level custom error page:

  1. Log into your Cloudflare account.
  2. Click the Configurations tab.
  3. In the left navigation, click Custom Pages.
  4. Identify your desired custom error page type, then click the Custom Pages button. A Custom Page dialog will appear.
  5. Enter the URL of the custom error page you customized in your origin server, then click Publish.
video showing how to navigate to the account level custom error page section of the Cloudflare dashboard

Domain level custom error page

To publish a domain level custom error page:

  1. Log into your Cloudflare account.
  2. Choose the domain for which you would like to publish a custom error page.
  3. Click the Custom Pages app.
  4. Identify your desired custom error page type, then click the Custom Pages button. A Custom Page dialog will appear.
  5. Enter the URL of the custom error page you customized in your origin server, then click Publish.
video that demonstrates how to navigate to the page to publish domain level custom error pages in the cloudflare dashboard

Update custom error page after publishing

After successfully publishing the custom error page in the Custom Pages app, you can remove the page from your origin server. 

If in the future, you need to update your custom error page, you must re-publish the page at your origin and in the Cloudflare dashboard, even if the page URL remains unchanged.


Troubleshoot common custom pages issues

1xxx errors

Customize Error 1005 (blocked IP) via IP/Country Block, not 1XXX Errors.

1XXX Errors do not customize the following HTTP errors via the Custom Pages app:

  • 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

Custom error page size

Your custom error page cannot be blank and cannot exceed 1.43 MB. To avoid exceeding the custom error page limit, download collapsify to test your page size before publishing. 

General troubleshooting advice

  • If you encounter errors while attempting to preview or publish your custom error page, use an HTML validator to ensure that your code resolves properly. 
  • Make sure that you are serving the custom error page with an HTTP 200 status code.


Related Resources

Not finding what you need?

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