Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx add_header sets nothing in the response

Erroradd_header X-Frame-Options is in the config but curl -I does not show it

Short answer

Three things hide add_header. A location that has its own add_header drops every header from the server level. Without the always flag, headers are skipped on codes such as 404 and 500. And nginx must be reloaded after the edit. Check the response with curl -I, then match your case.

  • Applies to nginx 1.26 and 1.28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request the exact URL that fails and print only the headers. Also ask nginx which add_header lines it really loaded.

    curl -sI https://example.com/path
    sudo nginx -T 2>/dev/null | grep -n "add_header\|location "
  2. 2Match what you see, then jump to its fix

    1. 1The header is in server { } but missing for URLs that match a location with any add_headerA location has its own add_header, so the outer ones are droppedFix
    2. 2The header shows on 200 or 301 pages and is missing on 404, 403, 500 and similarThe response is an error code and add_header has no always flagFix
    3. 3Nothing changed at all, on any URLThe edit was never appliedFix

What does the error look like?

  • add_header X-Frame-Options is in the config but curl -I does not show it
  • Header appears on 200 pages but not on 404 or 500 pages
  • Header set in the server block disappears inside one location

Cause 1 of 3

A location has its own add_header, so the outer ones are dropped

1Check

nginx inherits add_header from the level above only when the current level defines none. One add_header in a location replaces all inherited ones for that location.

sudo nginx -T 2>/dev/null | grep -n -B2 -A8 "location"

2Fix

Repeat the shared headers in that location, move all headers into an included file used at each level, or on nginx 1.29.3 and later set add_header_inherit merge so values from the level above are appended.

server {
    add_header X-Content-Type-Options nosniff;
    add_header_inherit merge;   # nginx 1.29.3+

    location /assets/ {
        add_header Cache-Control "public, max-age=3600";
    }
}

3Verify

Both headers appear on a URL inside the location.

curl -sI https://example.com/assets/app.js

Confirmed by nginx.org

Did this fix it?

Cause 2 of 3

The response is an error code and add_header has no always flag

1Check

Without always, add_header only runs for 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308. Fetch a missing URL to see it.

curl -sI https://example.com/does-not-exist

2Fix

Add always to the directive, for instance for security headers you want on every response.

add_header Strict-Transport-Security "max-age=31536000" always;

3Verify

The 404 response now carries the header.

curl -sI https://example.com/does-not-exist | grep -i strict

Confirmed by nginx.org

Did this fix it?

Cause 3 of 3

The edit was never applied

1Check

Changes only take effect after a reload. A failed test also leaves the old config running, because the master process rolls back an invalid config.

sudo nginx -t

2Fix

Fix any error the test prints, then reload.

sudo nginx -s reload

3Verify

Request the URL again and look for the header.

curl -sI https://example.com/ | head -n 15

Confirmed by nginx.org

Did this fix it?

How do I stop it coming back?

  • Put all security headers in one snippet file and include it in every location that adds a header of its own.
  • Add always to headers that must appear on error pages.
  • After each change run nginx -t, reload, and check with curl -I.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.