caddy validate: Check a Caddyfile in CI
caddy validate parses and validates a config, adapting a Caddyfile to JSON if needed, and exits non-zero on any error.
caddy validate is the Caddy config gate. It runs the same adapt-and-load path the server uses at startup, so a passing validate means the server will accept the config.
What it does
caddy validate loads the config, adapts it from the Caddyfile (or another adapter) to Caddy JSON, and provisions the modules to confirm the whole config is valid, all without binding ports or serving traffic. It prints "Valid configuration" on success.
Common usage
caddy validate --config Caddyfile
# explicit adapter (default is caddyfile when the file is a Caddyfile)
caddy validate --config Caddyfile --adapter caddyfile
# validate a JSON config
caddy validate --config caddy.jsonOptions
| Flag | What it does |
|---|---|
| --config <file> | Path to the config file to validate |
| --adapter <name> | Config adapter to use (e.g. caddyfile) |
| --envfile <file> | Load environment variables from a file first |
In CI
Run caddy validate --config Caddyfile as a required check. It catches adapter errors that caddy fmt cannot, because it fully provisions modules. In a container: docker run --rm -v $PWD/Caddyfile:/etc/caddy/Caddyfile caddy:2 caddy validate --config /etc/caddy/Caddyfile.
Common errors in CI
Error: adapting config using caddyfile: ... means the Caddyfile failed to parse; the message names the line. "unrecognized directive" means a typo or a directive from a plugin not in this build. "getting config adapter: unknown adapter" means a bad --adapter name. A validate that passes but the server still fails usually means a runtime concern like a port bind, which validate does not test.