[Support Guide] Why are my _headers file rules not working as expected?

Last reviewed by Netlify Support in November 2024

Netlify sites can add additional HTTP response headers using a _headers file. There is more about this in our public docs. This can be done using both a file named _headers and in netlify.toml.

However, what follows is specifically about the rules being added using the _headers file.

Key points

I want to stress three key points about the formatting of this file:

  1. The path/URL lines must begin completely at the start of the line (no preceding spaces).
  2. The header lines must be indented exactly two spaces (not tabs).
  3. All header line or lines and their associated path line must occur with no newlines in between them.

Examples: incorrect formatting

Here are examples of what will not work (and why not).


 /*
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
  • Why doesn’t it work? → there is a space before the path rule on the first line

/*
 X-Frame-Options: DENY
 X-XSS-Protection: 1; mode=block
  • Why doesn’t it work? → only one space before the header lines

/*
  X-Frame-Options: DENY

  X-XSS-Protection: 1; mode=block
  • Why doesn’t it work? → There is a space between the two header lines.

Example: correct formatting

Finally, here is the correct syntax & spacing (copied directly from this section of the docs page above):

/*
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block

I hope this clarifies the formatting requirements of this file. If there are questions, though, please reply below and we’ll be happy to answer them.

4 Likes

if anyone is trying to enable HTTP/2 Server Push via _headers, please also note that this is not offered by Netlify at this time. HTTPS (SSL) | Netlify Docs

1 Like