Caddy reload hangs forever after adding a new domain

Adding a vhost for a fresh domain and running caddy reload made the command hang indefinitely. The existing sites kept serving, but the reload never returned, which looks like Caddy is broken. It isn’t.

Root cause

Caddy provisions a TLS certificate via ACME (Let’s Encrypt) on reload. For the HTTP-01 challenge to succeed, the domain’s DNS must already resolve to the server. If you add the vhost before pointing DNS at the box, Caddy blocks waiting on an ACME challenge that can never complete — the validating server can’t reach your host at that domain — and the reload hangs.

The fix

Point DNS first, then add the vhost. Create the A/AAAA record for the new domain at the server’s IP, let it propagate (confirm with dig +short newdomain.com), and only then add the Caddy site block and reload. Once DNS resolves to the box, the reload returns and the certificate is issued automatically.

If you’ve already wedged a reload, set the DNS record and the in-flight ACME attempt will eventually succeed once propagation completes.

Two hard-won companions

• caddy validate does NOT catch this. Validation checks config syntax; it happily passes a config that then hangs at runtime on ACME. Don’t treat a clean validate as “safe to go live.”
• validate also misses a bad log-file path. A log destination Caddy can’t write crashes it at start, and validate won’t flag it. Verify the log path is writable as part of deploy.

On a shared box, reload — never restart

caddy reload --config /etc/caddy/Caddyfile

Never caddy restart / systemctl restart caddy on a server hosting multiple sites: a restart tears down every vhost (and re-triggers ACME for all of them). reload swaps config with zero downtime for the sites that are fine.