# How to set X-Frame-Options on Caddy

> Set X-Frame-Options on Caddy with the header directive, pair it with CSP frame-ancestors, drop the application's copy behind reverse_proxy and allow one path. Tested.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/x-frame-options/caddy/
Updated: 2026-10-22
Tested on: Caddy 2.9, 2.10 and 2.11

## In short

- Add `X-Frame-Options "DENY"` and a Content-Security-Policy with `frame-ancestors 'none'` to a `header` block in the site. Use `SAMEORIGIN` and `'self'` if your own pages frame each other.
- Caddy sends the header on its own 404 pages and on redirects without any extra flag.
- Behind `reverse_proxy`, an application that sends X-Frame-Options too produces two headers, and `DENY` plus `SAMEORIGIN` blocks framing everywhere. Add `header_down -X-Frame-Options` inside the proxy block.
- To let a partner embed one path, use two named matchers: the default headers on `not path /embed/*`, and a CSP with the partner's origin on `path /embed/*`.
- Avoid `header /embed/* -X-Frame-Options` for this: Caddy defers deletions, and its own 404 pages under that path keep the header.

## The short answer

Add both headers to the site block in your Caddyfile:

```caddyfile
example.com {
	header {
		Content-Security-Policy "frame-ancestors 'none'"
		X-Frame-Options "DENY"
	}
	root * /var/www/example
	file_server
}
```

```sh
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy
```

If you already send a Content-Security-Policy, add `frame-ancestors 'none'`
to that policy instead of the first line. Every snippet below was run on
Caddy 2.9, 2.10 and 2.11 and checked with `curl`, on a page, a 404, a
redirect, a proxied application and an application that was down.

`DENY` blocks every frame, including your own. If your site frames its own
pages, use `SAMEORIGIN` and `frame-ancestors 'self'`. The
[X-Frame-Options overview](/guides/x-frame-options/) explains the two values
and why `frame-ancestors` overrides the older header in current browsers.

## Before you start

Find every site block, `header` directive and proxy in your Caddyfile:

```sh
grep -nE "^[^ \t#].*\{|header|X-Frame-Options|frame-ancestors|reverse_proxy|php_fastcgi|import" /etc/caddy/Caddyfile
```

You are looking for three things:

- **Every site that serves pages.** Caddy adds no X-Frame-Options on its own.
- **Proxied applications** that may send X-Frame-Options themselves. Two
  headers cause trouble (step 3).
- **Pages that are framed on purpose,** such as widgets or previews. They need
  their own rule (step 4).

## Step 1: choose DENY or SAMEORIGIN

| Your site | Caddyfile lines |
| --- | --- |
| Never frames its own pages | `X-Frame-Options "DENY"` and `frame-ancestors 'none'` |
| Frames its own pages, such as admin previews | `X-Frame-Options "SAMEORIGIN"` and `frame-ancestors 'self'` |
| Is embedded by another site on some pages | One of the above, plus step 4 for those pages |

Keep the two headers in agreement. Current browsers apply `frame-ancestors`
and ignore X-Frame-Options when both are present, so a mismatch means older
clients and current ones behave differently. Do not use `ALLOW-FROM`: browsers
ignore it and the page can be framed by anyone.

## Step 2: which responses get the header

A plain `header` block acts on every response of the site. In our test:

| Response | X-Frame-Options |
| --- | --- |
| A page from `file_server` | Present |
| A 404 from `file_server` | Present |
| A `301` from a `redir` in the site | Present |
| A file under `/assets/` with its own `header /assets/* Cache-Control …` line | Present |
| Caddy's automatic HTTP to HTTPS redirect | Absent |

Unlike Nginx and Apache, there is no `always` flag to remember, and a line
that sets another header for one path keeps X-Frame-Options. The automatic
redirect has no page to protect.

To send the same headers from several sites, put them in a snippet that each
site imports. The
[security headers hub for Caddy](/guides/security-headers/caddy/) shows one
snippet with all six security headers.

## Step 3: one header behind reverse_proxy

Many frameworks and security middlewares send X-Frame-Options by default. A
`header` block runs before the proxy, and Caddy keeps the application's
header next to its own. Our test, with an application sending `SAMEORIGIN`:

```http
HTTP/2 200
x-frame-options: DENY
x-frame-options: SAMEORIGIN
```

Browsers combine the two values, see a conflict and block the page in every
frame, so same-site previews break. WebSec0 reads both values like a browser
and grades the conflict as a warning, worth 7 of 15 points.

Pick one owner. If it is Caddy, drop the application's header as the response
comes back from the proxy:

```caddyfile
example.com {
	header {
		Content-Security-Policy "frame-ancestors 'none'"
		X-Frame-Options "DENY"
	}
	reverse_proxy 127.0.0.1:8080 {
		header_down -X-Frame-Options
		header_down -Content-Security-Policy
	}
}
```

Our test then returned `DENY` once on the application's pages and 404s, and on
Caddy's 502 when the application was down. The second `header_down` line
removes the application's own CSP; keep it only if Caddy owns the whole
policy. Do not use the `>` prefix instead: it replaces the application's
value, but Caddy's own 502 then has no header at all.

If the application sends a CSP with `frame-ancestors`, you can also let it
own framing and drop the Caddy lines: browsers apply `frame-ancestors` either
way.

## Step 4: let a partner embed one path

To let `partner.example` frame the pages under `/embed/` and keep everything
else at `DENY`, split the site with two named matchers:

```caddyfile
example.com {
	@embed path /embed/*
	@not_embed not path /embed/*

	header @not_embed {
		Content-Security-Policy "frame-ancestors 'none'"
		X-Frame-Options "DENY"
	}
	header @embed Content-Security-Policy "frame-ancestors 'self' https://partner.example"

	root * /var/www/example
	file_server
}
```

What our test returned:

| URL | Headers |
| --- | --- |
| `/` | `X-Frame-Options: DENY` and `frame-ancestors 'none'` |
| `/embed/` | `frame-ancestors 'self' https://partner.example` only |
| `/embed/does-not-exist` (404) | `frame-ancestors 'self' https://partner.example` only |

The obvious alternative leaves a gap. With the default headers on the whole
site and `header /embed/* -X-Frame-Options` in a `route` block, `/embed/` lost
the header, but the 404 under it still sent `X-Frame-Options: DENY`. Caddy
defers a line that deletes a field until the response is written, and its own
error pages skip deferred lines. That 404 is harmless, since browsers ignore
X-Frame-Options when the CSP has `frame-ancestors`, but the matchers avoid it.

If your full CSP is defined in the site, copy the whole policy into the
`@embed` line and change only `frame-ancestors`. WebSec0 passes these pages
too, since their CSP contains `frame-ancestors`.

## Verify it

Check a page, an error page and a static file. Use your own host name:

```sh
curl -sI https://example.com/ | grep -iE "^x-frame-options|^content-security-policy"
curl -sI https://example.com/does-not-exist | grep -iE "^x-frame-options|^content-security-policy"
curl -sI https://example.com/assets/app.css | grep -iE "^x-frame-options|^content-security-policy"
```

Each should print `x-frame-options: DENY` and a policy with
`frame-ancestors`. Count the X-Frame-Options headers to catch duplicates. The
result should be `1`:

```sh
curl -sI https://example.com/ | grep -ci '^x-frame-options:'
```

Then scan the site with WebSec0. The headers report shows the value it
received and whether it passes.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| No X-Frame-Options at all | Caddy adds none by default | Add the `header` block to every site, or import a snippet. |
| Two `X-Frame-Options` headers | The proxied application sends one too | Add `header_down -X-Frame-Options` inside `reverse_proxy`. |
| Header missing on 502 pages | `>` in front of the field | Drop the `>` and use `header_down`. |
| Your own iframes stopped loading | `DENY`, or `SAMEORIGIN` and `DENY` both sent | Use `SAMEORIGIN` and `'self'`, and send one header. |
| A partner's embed is blank | X-Frame-Options or `frame-ancestors 'none'` on that path | Use the two matchers from step 4. |
| A 404 under the embed path keeps X-Frame-Options | A deferred `-X-Frame-Options` line | Harmless with `frame-ancestors`; use matchers to remove it. |
| WebSec0 shows a warning | Two different values, often one from the application | Keep one header with one value (step 3). |
| WebSec0 fails a header that is present | An invalid value, such as `ALLOW-FROM` | Replace it with `DENY` or `SAMEORIGIN`, or add `frame-ancestors` to your CSP. |
| Changes do not show up | Reload skipped, or a CDN cached old headers | `caddy validate` and reload, then purge the CDN. |

## Frequently asked questions

### Where do I put X-Frame-Options in a Caddyfile?

In a `header` block inside each site block, or in a snippet that every site imports. Caddy applies it to every response of the site, including its own 404 pages and redirects.

### What is the Caddyfile line for X-Frame-Options?

`header X-Frame-Options "DENY"`, or `SAMEORIGIN` instead of `DENY` if your own pages frame each other. Reload with `caddy validate` and `systemctl reload caddy`.

### Why does my response have two X-Frame-Options headers behind reverse_proxy?

Caddy sets its header before the proxy and keeps the application's. Add `header_down -X-Frame-Options` inside the `reverse_proxy` block to drop the application's copy.

### How do I allow framing for one URL on Caddy?

Define `@embed path /embed/*` and `@not_embed not path /embed/*`. Send X-Frame-Options and `frame-ancestors 'none'` on `@not_embed` only, and a CSP with `frame-ancestors 'self' https://partner.example` on `@embed`.

### Why does a 404 under my embed path still send X-Frame-Options?

A `header` line that deletes a field, such as `-X-Frame-Options`, is deferred until the response is written, and Caddy's own error pages skip deferred lines. Use matchers so the header is never set on that path.

### Does Caddy send X-Frame-Options by default?

No. Caddy sends no security headers of its own. Add the line to every site that serves pages.

## Sources

- [Caddyfile directive: header](https://caddyserver.com/docs/caddyfile/directives/header), Caddy
- [Caddyfile directive: reverse_proxy (header_down)](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#headers), Caddy
- [Request matchers: named matchers and not](https://caddyserver.com/docs/caddyfile/matchers), Caddy
- [HTML Standard: the X-Frame-Options header](https://html.spec.whatwg.org/#the-x-frame-options-header), WHATWG
- [X-Frame-Options header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options), MDN Web Docs
- [CSP: frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors), MDN Web Docs
