Format, adapt, and validate

Before you trust a Caddyfile, Caddy gives you three commands to check it. Each one goes a step deeper than the one before. Let’s see them in order.

Format

caddy fmt rewrites your Caddyfile with consistent indentation:

caddy fmt --diff Caddyfile

The --diff flag shows what would change without touching the file. Add --overwrite when you want to apply the changes.

Formatting sounds cosmetic. It’s not. It keeps diffs in version control readable, and Caddy logs a warning at startup when the file isn’t formatted. I run it before every commit.

Adapt

caddy adapt converts the Caddyfile to Caddy’s native JSON and prints the result:

caddy adapt --config Caddyfile --pretty

Read that JSON once, even if it looks verbose. You’ll see the routes Caddy built, in the order it will try them. You’ll also see configuration that was implicit in the Caddyfile, like the automatic HTTPS settings.

When routing behaves in a way you don’t expect, this output is where you find out why. The Caddyfile is what you meant. The JSON is what Caddy understood.

Validate

caddy validate is the strongest check:

caddy validate --config Caddyfile

Adaptation only converts the file. Validation loads the configuration and provisions every module, as if the server were starting for real. The only thing it skips is opening sockets.

A Caddyfile can adapt fine and still fail validation. A common case is a tls directive pointing at a certificate file that doesn’t exist on disk. Adaptation doesn’t care. Validation does, and it tells you before the running server ever sees the broken config.

On success it prints that the configuration is valid.

Make it a habit

Here is the sequence I use: format, adapt, validate, and only then load the configuration on a real server. It takes a few seconds and it catches typos on your laptop instead of in production.

Be careful with what validation cannot catch: runtime problems. It won’t tell you that port 443 is already taken, or that DNS doesn’t point at your machine. It checks the configuration, not the environment. When a valid config still fails to start, look at the environment.

Try this: add a tls /etc/caddy/missing.crt /etc/caddy/missing.key line to your site block, then run adapt and validate. Adapt succeeds. Validate fails with an error that names the missing file. Remove the line afterwards.