Cloudflare _headers Tester

By · Updated

Paste your Cloudflare Pages _headers file and the URLs you care about to see the final headers each one gets — after splats, placeholders, merging, and ! detach — and which line set them. The validator flags the mistakes Cloudflare ignores without a word.

_headers tester

File check No problems

How Cloudflare applies a _headers file

  1. Rules are blocks. An unindented line is a URL pattern; the indented Name: value lines under it are its headers. Lines starting with # are comments.
  2. Every matching rule applies, top to bottom. A request to /assets/app.js gets headers from both /* and /assets/*.
  3. Duplicates are joined with a comma. Setting the same header in two matching rules sends value1, value2, not the more specific one.
  4. ! Name removes earlier values. Use it before setting a header that a broader rule already set.
  5. Limits. 100 rules, 2,000 characters per line, one * per pattern, absolute URLs only with https:// and no port.
  6. Static assets only. Responses from Pages Functions or Worker code never get these headers, and a matching _redirects rule wins first.

Copy-ready _headers examples

Security headers for the whole site

/*
  Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
  Content-Security-Policy: default-src 'self'; frame-ancestors 'none'

Revalidate HTML, cache hashed assets for a year

/*
  Cache-Control: public, max-age=0, must-revalidate

/_astro/*
  ! Cache-Control
  Cache-Control: public, max-age=31536000, immutable

Without the ! Cache-Control line, assets would get both policies joined into one contradictory header.

CORS for one API path

/api/data/*
  Access-Control-Allow-Origin: https://app.example.com
  Access-Control-Allow-Methods: GET, OPTIONS
  Vary: Origin

Frequently asked

Why are my Cloudflare Pages _headers not applied?
The usual causes are formatting: header lines must be indented under their path, and an unindented "Name: value" line is read as a URL pattern instead. Other causes: an absolute URL starting with http:// instead of https://, a port in the pattern, two * splats in one pattern, or a file over the 100-rule or 2,000-character-per-line limit. Cloudflare skips these without an error. Also check that the file is named exactly _headers (no extension) and ends up in your build output folder, and that the response isn't coming from a Pages Function or a _redirects rule, which _headers never applies to.
What happens when several _headers rules match the same URL?
All of them apply, in the order they appear in the file. If two matching rules set the same header, Cloudflare joins the values with a comma, as in "X-Robots-Tag: noindex, nosnippet". That's fine for list-style headers but produces conflicting values for Cache-Control or Content-Security-Policy, so detach the earlier value first with "! Cache-Control".
How do I remove or override a header in _headers?
Write ! followed by a space and the header name, for example "! Cache-Control", under the more specific rule. It removes the header if an earlier rule in the file added it. To give one path a different value, detach and then set the header again on the next line. A detach placed above the rule it targets has no effect.
How do splats and placeholders work in _headers?
A * splat matches anything, including slashes, and its match can be reused in a header value as :splat. Only one splat is allowed per pattern. A named placeholder such as :version matches one path segment (anything but /), or one host label (anything but . or /) in an absolute URL, and can be reused in a value as :version. Each placeholder name can appear only once in a pattern.
Does _headers work with Cloudflare Workers?
Yes, for Workers static assets. The same file format applies to static files served from your assets directory. It doesn't apply to responses your Worker code generates, the same way it doesn't apply to Pages Functions. Set those headers in code.
Is header matching case-sensitive?
Header names are case-insensitive in HTTP, so X-Robots-Tag and x-robots-tag are the same header. This tester merges them that way. URL patterns are compared to the request path as written, so keep the pattern's case the same as your file paths.
Does this tester send my _headers file anywhere?
No. Parsing and matching run in your browser. Nothing is uploaded, so you can paste a production configuration safely.
All tools →