Skip to content

Commit

Permalink
[Support] Custom Pages: Add note (#17047)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pedrosousa @maheshwarip
pedrosousa authored and maheshwarip committed Dec 2, 2024
1 parent 4ace81c commit 48b1794
Showing 1 changed file with 63 additions and 67 deletions.
130 changes: 63 additions & 67 deletions ...d-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,26 @@
pcx_content_type: troubleshooting
source: https://support.cloudflare.com/hc/en-us/articles/200172706-Configuring-Custom-Pages-Error-and-Challenge-
title: Configuring Custom Pages (Error and Challenge)

---

## Overview

Cloudflare uses a wide range of [error codes](/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. 
Cloudflare uses a wide range of [error codes](/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.

:::note
:::note[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.

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.

:::note

Enable Origin Error Pages excludes errors 520 to 527.
Enable Origin Error Pages excludes errors 520 to 527.
:::

***
---

## Step 1: Create a custom page

Expand All @@ -34,93 +31,92 @@ 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>
<head></head>
<body>
::[REPLACE WITH CUSTOM ERROR TOKEN NAME]::
</body>
</html>
```

:::caution[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](/waf/reference/cloudflare-challenges/): `<meta name="referrer" (...) />`

* 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](/waf/reference/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: 
Here is sample code for a 5XX custom error page without styling:

```html
<!DOCTYPE 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>
<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. 
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. 
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 |
| Token | Available to |
| --------------- | ------------ |
| `::CLIENT_IP::` | All pages |
| `::RAY_ID::` | All pages |

:::caution

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

| **Token** | **Available to** |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| ::GEO:: | IP/Country Block |
| ::CAPTCHA\_BOX:: | Interactive Challenge<br/>Country Challenge (Managed Challenge)<br/>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 |
| Token | Available to |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `::GEO::` | IP/Country Block |
| `::CAPTCHA_BOX::` | Interactive Challenge<br/>Country Challenge (Managed Challenge)<br/>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 (i.e. return a 200 OK) otherwise an error will be thrown.
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.
- 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](/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.
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 (ie. `https://domain.com/5xx.html?removeimages` -> `https://domain.com/5xx.html`).
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
Expand Down Expand Up @@ -149,11 +145,11 @@ To publish a domain level custom error page:

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

Expand All @@ -167,31 +163,31 @@ If you block requests due to a [rate limiting rule](/waf/rate-limiting-rules/) a

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

**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
- 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.
- 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](/waf/custom-rules/)
* [Cloudflare challenges](/waf/reference/cloudflare-challenges/)
* [Troubleshooting Cloudflare errors](/support/troubleshooting/cloudflare-errors/)
* [IP Access rules](/waf/tools/ip-access-rules/)
* [Rate limiting rules](/waf/rate-limiting-rules/)
* [Firewall rules](/firewall/cf-firewall-rules/) (deprecated)
- [WAF custom rules](/waf/custom-rules/)
- [Cloudflare challenges](/waf/reference/cloudflare-challenges/)
- [Troubleshooting Cloudflare errors](/support/troubleshooting/cloudflare-errors/)
- [IP Access rules](/waf/tools/ip-access-rules/)
- [Rate limiting rules](/waf/rate-limiting-rules/)
- [Firewall rules](/firewall/cf-firewall-rules/) (deprecated)

0 comments on commit 48b1794

Please sign in to comment.