Caddy FAQ: Answers to Common Questions

This page collects the questions that come up again and again when people run Caddy for the first time, and the answers that are worth knowing. Most of them are not really about Caddy being difficult; they are about behaviour that is correct but surprising the first time you meet it: the adapter reordering your directives, the prefix disappearing under handle_path, the certificate challenge needing port 80, the server header that nobody asked for. Once the behaviour is expected, the problem usually disappears.

1. Installing and starting

Does Caddy need to run as root?

Only to bind ports 80 and 443, and even that can be arranged without root. Give the binary the capability to bind privileged ports and run it as a normal user.

sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy

Everything else, including writing certificates to the data directory, only needs write access to that directory.

Why does Caddy refuse to start with bind: address already in use?

Something else already holds the port. Automatic HTTPS needs 80 and 443, and both are shared with other services.

sudo ss -ltnp | grep -E ':(80|443)\s'

Stop the other service, or move Caddy to different ports with the bind directive. If the other service is a container or a cloud load balancer, the conflict may be inside a namespace rather than on the host.

Where does Caddy keep its certificates?

In the data directory, which is backed by the configured storage module and is a filesystem location by default.

PlatformData directoryConfiguration directory
Linux and BSD$HOME/.local/share/caddy$HOME/.config/caddy
macOS$HOME/Library/Application Support/Caddy$HOME/Library/Application Support/Caddy
Windows%AppData%\Caddy%AppData%\Caddy

The XDG_DATA_HOME and XDG_CONFIG_HOME variables override the Linux paths, and the packaged Linux service sets them to /var/lib/caddy and /var/caddy. The data directory holds private keys, certificates, and OCSP staples, so it must be persistent and writable by the process user. It is not a cache and should not be purged on a schedule.

Why is the configuration directory not where my Caddyfile is?

The configuration directory is not where configuration files belong. It is where Caddy persists the last active configuration, so that caddy run --resume can bring the process back with the same settings after a reboot. Your own files live wherever you put them.

2. Certificates and HTTPS

How do I get a certificate for a name that does not resolve publicly?

Use the internal certificate authority. The tls directive with the internal option asks for a certificate from the internal CA that Caddy runs itself instead of from a public one.

internal.example.com {
	tls internal
	respond "internal only"
}

The clients must trust Caddy local root certificate, which caddy trust installs into the trust store of the machine you run it on. Alternatively, set the local_certs global option to make internal the default for every site.

How do I issue a wildcard certificate?

Wildcards cannot be validated over the HTTP challenge, because there is no single host to point at. Use the DNS challenge, which requires a DNS provider plugin.

*.example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
	reverse_proxy localhost:9000
}

The plugin must be compiled into the binary. Confirm it is there with caddy list-modules, and install it with caddy add-package github.com/caddy-dns/cloudflare if it is missing.

Why did issuance fail?

The log message usually names the reason. The common causes are:

  • The name does not point at this host. The HTTP challenge fetches the token over the public internet, so the A and AAAA records must resolve to this server.
  • Port 80 is blocked. A firewall or an upstream load balancer that does not forward port 80 will break the HTTP challenge even when DNS is correct.
  • A CAA record forbids the CA. A CAA record that does not list the CA Caddy uses will cause every issuance attempt to fail with a specific error about the CAA record.
  • Rate limits. A public CA will refuse to issue too many certificates for one domain. This produces an error mentioning the rate limit, and it clears after several hours.
  • The clock is wrong. A server whose time has drifted will fail every challenge.

Can I use a certificate I already have?

Yes. Point tls at the certificate and the key.

example.com {
	tls /etc/ssl/example.com/fullchain.pem /etc/ssl/example.com/privkey.pem
	respond "ok"
}

Caddy will serve that certificate and stop trying to obtain one. It will not renew it for you.

3. Configuration and routing

Why is my directive not running?

Because the Caddyfile adapter sorts directives into a canonical order before it builds the configuration. The order in the file is not the order of execution.

Read the effective configuration to see what happened.

caddy adapt --config /etc/caddy/Caddyfile --pretty

When two directives must run in a specific order, say so with route, which preserves the written order.

Why did my URL prefix disappear?

handle_path strips the matched prefix before the inner handlers run. A request for /api/orders handled by handle_path /api/* arrives at the upstream as /orders.

Use handle instead when the upstream expects the full path.

Can one server host many sites?

Yes, and that is the normal case. Site blocks are matched on the Host header, and several blocks can share one server. Write them as separate blocks in one file, or as separate files brought together with import.

example.com {
	respond "main"
}

docs.example.com {
	respond "docs"
}

How do I reuse the same block of directives?

With a snippet. A snippet is a named block, defined in parentheses and imported where it is needed.

(security) {
	header {
		X-Content-Type-Options nosniff
		-Server
	}
}

example.com {
	import security
	respond "ok"
}

How do I put a value from the environment into the configuration?

Use the {$NAME} syntax. The value is resolved when the configuration is loaded.

reverse_proxy api.internal:8443 {
	header_up Authorization "Bearer {$API_TOKEN}"
}

Load the values from a file with caddy run --envfile /etc/caddy/env. The file uses KEY=VALUE lines and supports comments beginning with #.

4. Reverse proxying

Why do I get a 502 Bad Gateway?

The proxy could not get a usable response from the upstream. Test the upstream directly from the same host, on the same network path.

curl -v http://127.0.0.1:9000/health

If that fails, the problem is the application. If it succeeds, the problem is usually the address Caddy is dialling, a firewall between the two, or an upstream that rejects the Host header.

The proxy log contains the upstream error, so read it rather than guessing.

sudo journalctl -u caddy -n 100 --no-pager

Do I need to configure WebSockets?

No. Caddy handles the HTTP upgrade natively, and there is nothing to enable. If a WebSocket connection fails, look elsewhere: a proxy in front of Caddy that does not forward the Upgrade header, an upstream with an aggressive idle timeout, or a handle_path that rewrites the path the socket lives at.

How do I pass the real client IP to the backend?

Caddy sets X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host by default. The backend must be configured to trust them, and Caddy must be told which proxies in front of it to believe.

reverse_proxy localhost:9000 {
	trusted_proxies 10.0.0.0/8
}

Without trusted_proxies, Caddy treats the immediate peer as the client, which is correct when nothing sits in front of it and wrong when a load balancer does.

How do I spread traffic over several backends?

Name them and choose a policy.

reverse_proxy backend-1:8080 backend-2:8080 {
	lb_policy round_robin
	lb_try_duration 5s
}

Without health checks the policy has nothing to work with, so add them.

	health_uri /healthz
	health_interval 10s
	health_timeout 5s

Why does my backend reject the request?

Most often because of the Host header. Caddy preserves the original Host by default, and an application deployed for localhost:8080 will often refuse a request whose Host is example.com.

reverse_proxy localhost:9000 {
	header_up Host {http.reverse_proxy.upstream.hostport}
}

5. Performance and caching

Does Caddy have a caching directive?

Not as a general-purpose HTTP cache. Static file caching is done with headers, which is usually what is wanted.

example.com {
	root * /srv/www
	@assets path /assets/*
	header @assets Cache-Control "public, max-age=31536000, immutable"
	file_server
}

For a dynamic cache, put one in front of Caddy or use a module.

How do I serve Brotli?

The encode directive handles zstd and gzip. For Brotli, produce the compressed files ahead of time and serve them directly.

example.com {
	root * /srv/www
	file_server {
		precompressed zstd br gzip
	}
}

Caddy then serves style.css.br to a client that advertises Brotli, and style.css to one that does not.

Caddy is using a lot of memory

Caddy is a Go program, and the garbage collector decides when to reclaim memory rather than the program doing it directly. Setting a soft memory limit usually makes the collector work harder instead of letting the heap grow.

GOMEMLIMIT=512MiB caddy run --config /etc/caddy/Caddyfile

Before tuning this, check that the memory is not simply the working set you expect, for example a large number of certificates, or access logs buffered in memory.

Why is compression making some responses slower?

The encode directive only compresses responses above minimum_length, which defaults to 512 bytes, and only for content types that benefit. Very small responses and already-compressed formats such as JPEG or PNG are excluded by the default matcher.

6. Security

How do I remove the Server header?

Use the - prefix on the header directive.

example.com {
	header -Server
	respond "ok"
}

How do I restrict access to an address range?

Use a named matcher with not remote_ip, then respond to everything that does not match.

example.com {
	@notAllowed {
		not remote_ip 10.0.0.0/8 192.168.0.0/16
	}
	respond @notAllowed "Forbidden" 403
	respond "ok" 200
}

How do I add password authentication?

Hash the password with the built-in helper, then reference the hash.

caddy hash-password --plaintext "correct horse battery staple"

The output is a bcrypt hash by default, and it is placed in the configuration directly.

example.com {
	basic_auth {
		Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
	}
	respond "Welcome, {http.auth.user.id}" 200
}

Use argon2id instead of the default bcrypt when you want a key derivation function that is harder to attack with specialised hardware.

Is it safe to expose the admin endpoint?

The admin endpoint can replace the entire configuration of the process, so it must not be reachable by anyone who should not control your server. Keep it on the loopback interface, which is the default, or move it to a unix socket whose permissions control access.

{
	admin unix//run/caddy-admin.sock
}

If you bind it to a routable address, add origins and enforce_origin and put it behind something that authenticates.

7. Logs and debugging

Where do the logs go?

To standard error by default, which means to the journal under systemd.

sudo journalctl -u caddy -f

Access logs are separate from the runtime logs and are only produced when the log directive is configured.

example.com {
	log {
		output file /var/log/caddy/access.log {
			roll_size 100mb
			roll_keep 10
			roll_keep_for 720h
		}
		format json
	}
	respond "ok"
}

How do I get machine-readable logs?

Set the format to json.

{
	log default {
		output stdout
		format json
	}
}

How do I see what the server is doing in detail?

Turn on debug logging temporarily. It is extremely verbose, so remove it afterwards.

{
	debug
}

How do I skip logging a noisy endpoint?

Use the skip_log directive for the requests you do not want to see, such as health checks.

example.com {
	@health path /healthz
	skip_log @health
	respond "ok"
}

What is the fastest way to debug a configuration?

In this order:

  1. caddy validate --config Caddyfile provisions the modules without starting them and catches most errors.
  2. caddy adapt --config Caddyfile --pretty shows the JSON the adapter produced, which reveals what your directives actually turned into.
  3. caddy run --config Caddyfile --watch reloads automatically as you edit, which is convenient in development and explicitly not recommended in production.
  4. curl -v shows the exact request and response, including the certificate and the headers.

8. Questions that come up again and again

Can I use Caddy behind an existing load balancer?

Yes. Bind the site to the internal address, keep Automatic HTTPS on so Caddy still manages its own certificates, and let the load balancer terminate the connection to the client.

{
	default_bind 127.0.0.1
}

example.com {
	reverse_proxy localhost:9000
}

Two details matter. The load balancer must use X-Forwarded-Proto so that Caddy knows the original scheme, and Caddy must be told which proxies to trust with trusted_proxies.

How do I redirect everything to HTTPS?

Automatic HTTPS already redirects plain HTTP to HTTPS for sites it manages. If you have explicitly disabled it or are proxying, write the redirect yourself.

example.com {
	@http {
		not protocol https
	}
	redir @http https://{host}{uri} permanent
}

How do I run several Caddy instances on one machine?

Give each one its own admin endpoint, its own data directory, and its own set of ports.

CADDY_ADMIN=localhost:2020 XDG_DATA_HOME=/srv/caddy-one/data \
	caddy run --config /etc/caddy/one/Caddyfile

The admin endpoint is the part that collides most often, and setting CADDY_ADMIN is the simplest way to avoid it.

Why does Caddy ignore my configuration file?

Three reasons, in order of likelihood. The file is not the one being loaded: check the --config flag and the ExecStart line of the service unit. The adapter produced something different from what you wrote: read it with caddy adapt --pretty. Or the change was never applied, because the file was edited on disk while the running process kept its old configuration: reload it.

How do I find out which configuration the running server is using?

Ask the server, not the filesystem.

curl -s http://localhost:2019/config/ | jq

That is the configuration in force, after the adapter and after any change made through the API. It is the only answer that cannot be stale.

caddy faqtroubleshooting502 errorcertificate issuance

Approach:

The scenario is a site that returns a 502 for some requests and does not issue a certificate for one hostname, while other hostnames on the same server work fine. The temptation is to change the configuration until the symptom disappears, but a 502 and a failed issuance are produced by different subsystems, and one fix cannot address both. The correct approach is to separate the two failures, and for each one to identify the layer that owns it: the transport layer for the proxy failure, and the challenge layer for the certificate failure.

Steps:

  1. Read the effective configuration from the running process with GET /config/ rather than from the file on disk, because the file may not be what was loaded, and the adapter may have changed the shape of what you wrote.
  2. For the 502, read the proxy error from the log, which names the upstream address that was dialled and the reason the dial or the round trip failed. Access logs and runtime logs are separate streams, so check both.
  3. Test the upstream directly from the Caddy host, on the same address Caddy uses, to separate a broken application from a broken path between the two machines.
  4. If the upstream answers directly, check the two things that make a healthy upstream look broken through a proxy: the Host header Caddy sends, and whether the request is a WebSocket upgrade that an intermediary is dropping.
  5. For the certificate, read the ACME error in the log. It names the specific reason: a name that does not resolve to this host, a blocked port 80, a CAA record, a rate limit, or clock drift.
  6. Verify the name resolution and the port from outside the host, since the challenge is fetched over the public internet and a configuration that looks correct from the inside can still fail.
  7. Change one thing at a time and apply it with caddy reload rather than a restart, so that each change is independently attributable and the previous configuration stays live if it makes things worse.

Answer:

The two problems have different owners and different fixes.

For the 502, the proxy layer reports the cause in the log rather than in the response body, and the response body is deliberately uninformative.

sudo journalctl -u caddy --since "5 minutes ago" --no-pager | grep -i upstream

The upstream is then tested directly, with the same address Caddy dials.

curl -v http://10.0.1.7:9000/health

If the application answers but rejects the request, the Host header is the usual culprit, and the fix is to send the upstream address instead of the public name.

reverse_proxy 10.0.1.7:9000 {
	header_up Host {http.reverse_proxy.upstream.hostport}
}

For the certificate, the ACME error in the log is the answer, and the fix depends on which error it is. If the name does not resolve to this host, the fix is DNS. If port 80 is blocked, the fix is to forward it or to switch to the DNS challenge. If a CAA record is the problem, the record must list the CA. If it is a rate limit, the fix is to wait.

For an internal name that will never resolve publicly, the fix is to stop asking a public CA.

internal.example.com {
	tls internal
	reverse_proxy localhost:9000
}

The result is that the 502 disappears once the upstream is reachable with the Host header it expects, and the certificate is issued once the challenge can actually complete, either publicly or through the internal CA.

Found an issue with this content?

Tell us what could be improved.