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.
Alternatively, Enterprise customers can customize 5XX error pages at their origin via Enable Origin Error Pages in the Custom Pages app in the dashboard..
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>
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 5XX custom error page without styling:
<!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 Legacy 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 |
| Token | Available to |
|
::GEO:: |
IP/Country Block |
|
::CAPTCHA_BOX:: |
|
|
::IM_UNDER_ATTACK_BOX:: |
|
|
::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. 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.
You can check if your page is fine using the following tool: Collapsify
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.
Account-level custom error page
To publish an account level custom error page:
- Log into your Cloudflare account.
- Click the Configurations tab.
- In the left navigation, click Custom Pages.
- Identify your desired custom error page type, then click the Custom Pages button. A Custom Page dialog will appear.
- Enter the URL of the custom error page you customized in your origin server, then click Publish.
Domain level custom error page
To publish a domain level custom error page:
- Log into your Cloudflare account.
- Choose the domain for which you would like to publish a custom error page.
- Click the Custom Pages app.
- Identify your desired custom error page type, then click the Custom Pages button. A Custom Page dialog will appear.
- Enter the URL of the custom error page you customized in your origin server, then 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
IP/Country Block vs 1000 Class Errors pages
If you block countries or IP addresses with IP Access Rules, affected visitors will get a 1005 error and see your IP/Country Block custom page.
If you block countries or IP addresses with firewall rules, affected visitors will see 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, 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.