Troubleshooting - DNZ

Start with dnz doctor (or Settings → Health check): it finds most of these by itself and prints the fix. See Health check.

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`
`nameserver 127.0.0.1` in `/etc/resolv.conf` keeps disappearing	Something rewrites the file. Set `DNS=127.0.0.1` in systemd-resolved instead; see Use DNZ as this server’s resolver
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 doctor                          # the health check: what is wrong, and how to fix it
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