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

A Content Security Policy (CSP) controls which scripts and resources a browser is allowed to load on a page. Challenge pages depend on specific Cloudflare scripts, so custom CSP configurations can prevent challenges from working.

You cannot set your own CSP or Referer-Policy on challenge pages using <meta> tags or Transform Rules. Origin response headers can still be modified in a challenge page context, but doing so may cause the challenge to break.

If you have a Transform Rule that modifies HTTP response headers across your website (for example, adding custom CSP headers), the rule will interfere with challenge pages and cause them to fail.

To prevent this, modify your Transform Rule expression to exclude challenge page responses. Add the following condition to the beginning of your expression:

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

This expression skips your header modifications when Cloudflare serves a challenge page, so the challenge scripts load correctly.

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 you configure a custom challenge page, Cloudflare fetches your uploaded HTML template and replaces the ::CF_WIDGET_BOX:: placeholder with the challenge script.

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>