Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Additional configuration

Multi-language support

Refer to supported languages for more information.

Favicon customization

Cloudflare Challenges take the favicon of your website using GET /favicon.ico and displays it on the Challenge Page.

You can customize your favicon by using the HTML snippet below.

HTML element
<link rel="shortcut icon" href="<FAVICON_LINK>" />

Custom Content Security Policy (CSP) and error pages

Cloudflare-served Challenge Pages operate in a strictly controlled environment to maximize security and ensure the challenge mechanism functions correctly. Because of this, you cannot set your own Content Security Policy (CSP) or Referer-Policy using <meta> tags or Transform Rules on Challenge Pages. Origin headers can be modified within the Challenge Page context and are not immutable, but they may cause issues.

If you have an active Transform Rule configured to modify HTTP response headers globally across your website, such as adding custom CSP headers, this rule will interfere with and cause the Challenge Page to fail.

To prevent this conflict, you must modify your Transform Rule expression to explicitly exclude Challenge Page error types. Prefix your Transform Rule expression with the following logical exclusion:

not cf.response.error_type in {"managed_challenge" "iuam" "legacy_challenge" "country_challenge"}

This exclusion ensures that your custom header modification logic is only applied to traffic destined for your origin, allowing Cloudflare's Challenge Platform to function without being impacted by conflicting response headers.

Custom Challenge Pages

Before defining a custom Challenge Page in your Cloudflare account, you will need to design and code that page. It can be hosted on your own web server or using a Cloudflare product like Snippets.

Refer to Design your custom error page for more information.

How it works

When a zone has a custom Challenge Page configured, your uploaded HTML is fetched from the Custom Pages Worker (KV-backed).

Cloudflare replaces the ::CF_WIDGET_BOX:: placeholder token with the full challenge bootstrap <script> block.

Placeholder tokens

The custom error token provides diagnostic information or specific functionality that appears on the error page. Refer to Error tokens for more details.

  • ::CF_WIDGET_BOX::
  • ::CAPTCHA_BOX::
  • ::IM_UNDER_ATTACK_BOX::
  • ::CLIENT_IP::
  • ::RAY_ID::
  • ::GEO::

Requirements

  1. ::CF_WIDGET_BOX:: must appear exactly once in the body. This is where the challenge script is injected.
  2. <head> tag must be present.
  3. Cloudflare will set cTplC: 1 in the browser's window._cf_chl_opt when a custom template is in use. Do not add your own window._cf_chl_opt. Any existing definition will cause conflicts.
  4. Do not block /cdn-cgi/challenge-platform/ paths via Content Security Policy (CSP). Challenges will not work correctly with this kind of block in place.
  5. The page is served for all three challenge types (managed, interactive, non-interactive) if you use ::CF_WIDGET_BOX::.

Templates

Example
<!DOCTYPE html>
<html lang="en-US">
<head>
  <title>Example Title</title>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
</head>
<body>
  ::CF_WIDGET_BOX::
</body>
</html>