> ## Documentation Index
> Fetch the complete documentation index at: https://dnzwithazee.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common problems when deploying DNZ and how to fix them.

| 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](/deploy/port-53) |
| `Permission denied` on port 53 | Run it with the [systemd unit](/deploy/systemd), 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](/dns/query-logs) |
| Sign in with Cloudflare doesn't redirect back | Open DNZ over `https://`. See [HTTPS and reverse proxies](/deploy/https) |
| `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](/deploy/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

```bash theme={null}
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](/dns/forwarding#diagnose-an-upstream).

## More specific guides

* Dynamic updates refused: [Dynamic updates](/dns/dynamic-updates#troubleshooting)
* DNSSEC validation failures: [DNSSEC](/dns/dnssec)
* A proxied name doesn't work: [Routing checks](/proxy/routing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.