Troubleshooting

permission denied reading /var/log/caddy/access.log

Caddy writes as caddy:caddy 0600.

sudo caddy-analyze /var/log/caddy/access.log
# or persistently
sudo usermod -aG caddy $USER
# re-login, then
caddy-analyze /var/log/caddy/access.log

Cannot connect to the Docker daemon / docker.sock: permission denied

sudo usermod -aG docker $USER  # re-login
# or
sudo caddy-analyze docker://caddy
# if guard must block host traffic too:
sudo caddy-analyze guard --firewall-backend hybrid docker://caddy

k8s:// — no such pod / cannot list resource

kubectl config current-context
kubectl get pods -n production | grep caddy
kubectl auth can-i get pods/log -n production
# fix namespace
caddy-analyze k8s://caddy-xxx -n production
caddy-analyze config k8s://caddy-xxx -n production  # remember

journalctl:// — No journal files

systemctl status caddy  # is it caddy.service?
journalctl -u caddy.service --no-pager | head
sudo usermod -aG systemd-journal $USER  # re-login
# or
sudo caddy-analyze journalctl://caddy.service

GeoIP — country/asn empty or download fails

Auto-download from P3TERX mirror to ~/.config/caddy-analyzer/GeoLite2-*.mmdb on first use.

ls ~/.config/caddy-analyzer/*.mmdb
# behind proxy
https_proxy=http://proxy:8080 caddy-analyze top country testdata/sample.log
# custom path
caddy-analyze --geoip-db /usr/share/GeoIP/GeoLite2-Country.mmdb top country testdata/sample.log
# tuning (see Configuration)
caddy-analyze --geo-cache-ttl 48h --geo-cache-size 100000 top country testdata/sample.log

guard — iptables: permission denied / No chain/target

Guard modifies firewall — must run as root.

sudo caddy-analyze guard /var/log/caddy/access.log
# timeout on huge ruleset
sudo caddy-analyze guard --iptables-timeout 30s /var/log/caddy/access.log
# Docker host needs DOCKER-USER
sudo caddy-analyze guard --firewall-backend hybrid docker://caddy

blocklist refresh slow / fails

caddy-analyze blocklist list
# behind proxy
https_proxy=http://proxy:8080 caddy-analyze blocklist refresh
# custom cache
caddy-analyze blocklist refresh --cache-dir /tmp/bl
# skip defaults
caddy-analyze blocklist refresh --no-default-blocklists --blocklist-config my.json

No output / empty report

Check filters: --from in the future, --ip CIDR mismatch, --country without GeoIP. Remove filters progressively.

caddy-analyze testdata/sample.log            # no filter → must show 68 lines
caddy-analyze --from 1h testdata/sample.log  # if 0, log is older than 1h
caddy-analyze --country IT testdata/sample.log  # if 0, GeoIP missing

Still stuck?

Open an issue with: caddy-analyze --version, full command, and the first 5 lines of the log (redact IPs). GitHub Issues

↑