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

guard — server IP protection / new bans suspended

Self-IP protection is enabled by default since v0.8.0. Discovery can fail because Internet/DNS is unavailable, outbound HTTPS is blocked, certificates fail validation, both discovery services fail, or configured IPv6 cannot reach the Internet. Direct requests ignore HTTP proxy settings; IPv4 success alone is insufficient if IPv6 discovery is also required.

Startup failure stops guard. Runtime failure retains known protected IPs and suspends new bans, leaving existing unrelated bans in place. The error includes the cause and restart with --protect-self=false to disable server IP checks. Guard retries on its 30-second refresh and before subsequent ban attempts.

# Check direct IPv4 connectivity (run on the guard server)
curl --noproxy '*' -4 --max-time 4 https://api.ipify.org
# If the server has IPv6 connectivity
curl --noproxy '*' -6 --max-time 4 https://api6.ipify.org
# Disable server-IP discovery; replace the example trusted address
sudo caddy-analyze guard /var/log/caddy/access.log \
  --protect-self=false --never-block 203.0.113.10

Add --protect-self=false to the service's startup arguments and restart it if guard runs as a service. This skips all automatic server-IP checks; explicit whitelist entries still apply. See guard → self-ban protection for scope and shared-NAT/multiple-WAN limitations.

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

↑