You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge.mdx
title: Configuring Custom Pages (Error and Challenge)
5
-
6
5
---
7
6
8
-
## Overview
9
-
10
-
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.
7
+
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.
11
8
12
9
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.
13
10
14
-
:::note
11
+
:::note[Notes]
12
+
13
+
- 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.
14
+
- 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.
15
15
16
-
500, 501, 503, and 505 responses do not trigger custom error pages to
17
-
avoid breaking specific API endpoints and other web applications.
18
16
:::
19
17
20
18
Alternatively, Enterprise customers can customize 5XX error pages at their origin via **Enable Origin Error Pages** in the **Custom Pages** app in the dashboard.
21
19
22
20
:::note
23
-
24
-
Enable Origin Error Pages excludes errors 520 to 527.
21
+
Enable Origin Error Pages excludes errors 520 to 527.
25
22
:::
26
23
27
-
***
24
+
---
28
25
29
26
## Step 1: Create a custom page
30
27
@@ -34,93 +31,92 @@ You can use the following custom error template to start building your page:
34
31
35
32
```html
36
33
<html>
37
-
<head></head>
38
-
<body>
39
-
::[REPLACE WITH CUSTOM ERROR TOKEN NAME]::
40
-
</body>
34
+
<head></head>
35
+
<body>
36
+
::[REPLACE WITH CUSTOM ERROR TOKEN NAME]::
37
+
</body>
41
38
</html>
42
39
```
43
40
44
41
:::caution[Warnings]
45
42
43
+
- 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.
44
+
- 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" (...) />`
46
45
47
-
* 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.
48
-
* 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" (...) />`
49
-
:::
46
+
:::
50
47
51
48
When published, any additional scripts, images, or stylesheets increase the size of your custom error page source by approximately 50%.
52
49
53
50
### Custom Page example
54
51
55
-
Here is sample code for a 5XX custom error page without styling:
52
+
Here is sample code for a 5XX custom error page without styling:
56
53
57
54
```html
58
-
<!DOCTYPE html>
55
+
<!doctype html>
59
56
<html>
60
-
<head>
61
-
<metacharset="utf-8">
62
-
<title>5XX Level Errors page</title>
63
-
</head>
64
-
<body>
65
-
<h1>5XX Level Errors</h1>
66
-
<h2>::CLOUDFLARE_ERROR_500S_BOX::</h2>
67
-
</body>
57
+
<head>
58
+
<metacharset="utf-8" />
59
+
<title>5XX Level Errors page</title>
60
+
</head>
61
+
<body>
62
+
<h1>5XX Level Errors</h1>
63
+
<h2>::CLOUDFLARE_ERROR_500S_BOX::</h2>
64
+
</body>
68
65
</html>
69
66
```
70
67
71
-
***
68
+
---
72
69
73
70
## Step 2: Select your custom error tokens
74
71
75
-
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.
72
+
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.
76
73
77
-
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.
74
+
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.
78
75
79
76
The following tables list each custom error token grouped by the applicable custom error page.
80
77
81
-
|**Token**|**Available to**|
82
-
| -------------- |---------------- |
83
-
|::CLIENT\_IP::| All pages|
84
-
|::RAY\_ID::| All pages|
78
+
| Token |Available to |
79
+
| ---------------| ------------ |
80
+
|`::CLIENT_IP::`| All pages |
81
+
|`::RAY_ID::`| All pages |
85
82
86
83
:::caution
87
-
88
-
Only one page-specific custom error token can be used per page.
84
+
Only one page-specific custom error token can be used per 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.
99
+
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.
104
100
105
-
***
101
+
---
106
102
107
103
## Step 4: Preview and Publish your custom page
108
104
109
105
After customizing your custom error page, there are two options for adding the page to Cloudflare:
110
106
111
-
* Account level: the custom error page will apply to every domain associated with your account.
112
-
* Domain level: the custom error page will apply to only one domain associated with your account.
107
+
- Account level: the custom error page will apply to every domain associated with your account.
108
+
- Domain level: the custom error page will apply to only one domain associated with your account.
113
109
114
110
:::note
115
111
116
112
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.
117
113
118
-
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.
114
+
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.
115
+
119
116
:::
120
117
121
118
:::note
122
-
123
-
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`).
119
+
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`).
124
120
:::
125
121
126
122
### Account-level custom error page
@@ -149,11 +145,11 @@ To publish a domain level custom error page:
149
145
150
146
### Update custom error page after publishing
151
147
152
-
After successfully publishing the custom error page in the **Custom Pages** app, you can remove the page from your origin server.
148
+
After successfully publishing the custom error page in the **Custom Pages** app, you can remove the page from your origin server.
153
149
154
150
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.
155
151
156
-
***
152
+
---
157
153
158
154
## Troubleshoot common custom pages issues
159
155
@@ -167,31 +163,31 @@ If you block requests due to a [rate limiting rule](/waf/rate-limiting-rules/) a
167
163
168
164
If you block countries or IP addresses with a firewall rule (now deprecated), affected visitors will get your **1000 Class Errors page**.
169
165
170
-
### 1xxx errors
166
+
### 1XXX errors
171
167
172
168
**1XXX Errors** do not customize the following HTTP errors via the Custom Pages app:
173
169
174
-
* 1001 - Unable to resolve
175
-
* 1003 - Bad Host header
176
-
* 1018 - Unable to resolve because of ownership lookup failure
177
-
* 1023 - Unable to resolve because of feature lookup failure
170
+
- 1001 - Unable to resolve
171
+
- 1003 - Bad Host header
172
+
- 1018 - Unable to resolve because of ownership lookup failure
173
+
- 1023 - Unable to resolve because of feature lookup failure
178
174
179
175
### Custom error page size
180
176
181
177
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.
182
178
183
179
### General troubleshooting advice
184
180
185
-
* 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.
186
-
* Make sure that you are serving the custom error page with an HTTP 200 status code.
181
+
- 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.
182
+
- Make sure that you are serving the custom error page with an HTTP 200 status code.
0 commit comments