Troubleshooting - DNZ

Symptom	Cause and fix
`Address already in use` on port 53	systemd-resolved or another DNS server holds the port. See Port 53 and systemd-resolved
`Permission denied` on port 53	Run it with the systemd unit, or `sudo setcap cap_net_bind_service=+ep /usr/local/bin/dnz`
The server can’t resolve names after turning off the stub	`/etc/resolv.conf` still points at `127.0.0.53`. Run `sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf`
Queries don’t show up in Query Logs	Forwarded queries only appear in the All queries view, which superadmins see. See Query logs
Sign in with Cloudflare doesn’t redirect back	Open DNZ over `https://`. See HTTPS and reverse proxies
`connecting to Postgres` or `connecting to MySQL` at startup	The database isn’t reachable with `DNZ_DATABASE_URL`. `dnz config check` shows the URL DNZ uses, without the password. See Database
`migrating the … database` at startup	The database user may not create tables. Postgres: make it the database’s owner. MySQL: `GRANT ALL ON dnz.*`
`docker ps` shows `unhealthy`	Check `docker compose logs dnz`. Usually a port that couldn’t be bound, or a `/data` volume that isn’t writable
Other DNZ servers don’t appear on the replication radar	The primary listens on `127.0.0.1`. Set `DNZ_HTTP_ADDR=0.0.0.0:8080`, or type its address under the radar
The audit log shows the proxy’s IP for every action	Set `DNZ_TRUSTED_PROXIES` to the reverse proxy’s address
A setting in `dnz.toml` has no effect	The environment wins over the file. Run `dnz config show` to see where each value comes from

Useful commands

dnz config show                     # effective settings and where they come from
dnz healthcheck                     # exit 0 when the API answers
journalctl -u dnz -f                # logs (systemd)
docker compose logs -f dnz          # logs (Docker)
sudo ss -lunp 'sport = :53'         # who listens on port 53
dig @127.0.0.1 example.com          # ask DNZ directly

An upstream doesn’t answer

Use the Diagnose button next to the upstream under Forwarding, or dnz forwarding diagnose <address>. It checks the route, ping, TCP port, TLS handshake, DNS queries, port 53 interception and a traceroute, and points at the likely cause. See Forwarding.

More specific guides

Dynamic updates refused: Dynamic updates
DNSSEC validation failures: DNSSEC
A proxied name doesn’t work: Routing checks