Cloudflare uses a wide range of [error codes](https://developers.cloudflare.com/support/troubleshooting/cloudflare-errors/) 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.

Notes

* Responses with 500, 501, 503, and 505 HTTP status codes do not trigger custom error pages to avoid breaking specific API endpoints and other web applications.
* Your custom error pages are not used if requests do not contain `accept-encoding` headers. In these cases, Cloudflare will show the standard error pages to website visitors.

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

Note

Enable Origin Error Pages excludes errors 520 to 527.

***

## 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
<html>
  <head></head>
  <body>
    ::[REPLACE WITH CUSTOM ERROR TOKEN NAME]::
  </body>
</html>
```

Warnings

* Your custom error page should include a page-specific custom error token if applicable and cannot exceed 1.43 MB. Also, it must include HTML `<head>` and `</head>` tags.
* Make sure that the `referrer` meta tag is not present in your custom error page's HTML code since it will disrupt [Cloudflare challenges](https://developers.cloudflare.com/fundamentals/security/cloudflare-challenges/): `<meta name="referrer" (...) />`

When published, any additional scripts, images, or stylesheets increase the size of your custom error page source by approximately 50%.

### Custom Page example

Here is sample code for a 5XX custom error page without styling:

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>5XX Level Errors page</title>
  </head>
  <body>
    <h1>5XX 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 **Interactive 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    |

Warning

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

| Token                            | Available to                                                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `::GEO::`                        | IP/Country Block                                                                                                          |
| `::CAPTCHA_BOX::`                | Interactive Challenge Country Challenge (Managed Challenge) Managed Challenge / I'm Under Attack Mode (Interstitial Page) |
| `::IM_UNDER_ATTACK_BOX::`        | JS Challenge                                                                                                              |
| `::CLOUDFLARE_ERROR_500S_BOX::`  | 5XX Errors                                                                                                                |
| `::CLOUDFLARE_ERROR_1000S_BOX::` | 1XXX Errors                                                                                                               |

***

## 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. Please keep in mind that all the external resources like images, CSS, and scripts will be inlined during the process. As such, all external resources need to be available (that is, they must return 200 OK) otherwise an error will be thrown.

***

## Step 4: Preview and 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.

Note

If Cloudflare cannot load your site or you have blocked the United States (US) via [IP Access rules](https://developers.cloudflare.com/waf/tools/ip-access-rules/) or WAF custom rules, publishing and previewing the error page will not work.

A common error might look like the following: `Error fetching page: Fetch failed, https://example.com/ipcountryblock.html returned 403 (Code: 1202)`. Make sure that you are serving the custom error page with an `HTTP 200` status code, and that no WAF rule is blocking or challenging your custom error page.

Note

When publishing the custom error page, the system will ignore query strings. This means that if the custom error page URL contains a query string the address published will remove `?` and anything after that (for example, `https://domain.com/5xx.html?removeimages` -> `https://domain.com/5xx.html`).

### Account-level custom error page

To publish an account level custom error page:

1. Log into your Cloudflare account.
2. Go to **Manage Account** > **Configurations**.
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 **Preview**.
6. Ensure all your styles and images are showing up as desired in the preview.
7. Once you are happy with the page preview, return to the **Custom Page** dialog, and click **Publish**.

### 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 **Preview**.
6. Ensure all your styles and images are showing up as desired in the preview.
7. Once you are happy with the page preview, return to the **Custom Page** dialog, and click **Publish**.

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

### Error pages for blocked requests

If you block countries or IP addresses with an [IP Access rule](https://developers.cloudflare.com/waf/tools/ip-access-rules/), affected visitors will get a `1005` error and your **IP/Country Block** custom page.

If you block countries or IP addresses with a [WAF custom rule](https://developers.cloudflare.com/waf/custom-rules/) and you do not configure a [custom response](https://developers.cloudflare.com/waf/custom-rules/create-dashboard/#configure-a-custom-response-for-blocked-requests) for blocked requests in the rule, affected visitors will get your **WAF Block** page.

If you block requests due to a [rate limiting rule](https://developers.cloudflare.com/waf/rate-limiting-rules/) and you do not configure a [custom response for blocked requests](https://developers.cloudflare.com/waf/rate-limiting-rules/create-zone-dashboard/#configure-a-custom-response-for-blocked-requests) in the rule, affected visitors will get your **429 Errors** page displaying a Cloudflare `1015` error.

If you block countries or IP addresses with a firewall rule (now deprecated), affected visitors will get your **1000 Class Errors page**.

### 1XXX errors

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

* 1001 - Unable to resolve
* 1003 - Bad Host header
* 1018 - Unable to resolve because of ownership lookup failure
* 1023 - Unable to resolve because of feature lookup failure

### 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, preview your page before publishing 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](https://validator.w3.org/) 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

* [WAF custom rules](https://developers.cloudflare.com/waf/custom-rules/)
* [Cloudflare challenges](https://developers.cloudflare.com/fundamentals/security/cloudflare-challenges/)
* [Troubleshooting Cloudflare errors](https://developers.cloudflare.com/support/troubleshooting/cloudflare-errors/)
* [IP Access rules](https://developers.cloudflare.com/waf/tools/ip-access-rules/)
* [Rate limiting rules](https://developers.cloudflare.com/waf/rate-limiting-rules/)
* [Firewall rules](https://developers.cloudflare.com/firewall/cf-firewall-rules/) (deprecated)
