> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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.

Start with `dnz doctor` (or **Settings → Health check**): it finds most of these by itself and prints
the fix. See [Health check](https://docs.dnzwithazee.com/admin/health-check.md).

| 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](https://docs.dnzwithazee.com/deploy/port-53.md) |
| `Permission denied` on port 53 | Run it with the [systemd unit](https://docs.dnzwithazee.com/deploy/systemd.md), 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](https://docs.dnzwithazee.com/deploy/port-53.md#use-dnz-as-this-servers-resolver) |
| Queries don't show up in Query Logs | Forwarded queries only appear in the **All queries** view, which superadmins see. See [Query logs](https://docs.dnzwithazee.com/dns/query-logs.md) |
| Sign in with Cloudflare doesn't redirect back | Open DNZ over `https://`. See [HTTPS and reverse proxies](https://docs.dnzwithazee.com/deploy/https.md) |
| `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](https://docs.dnzwithazee.com/deploy/database.md) |
| `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 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](https://docs.dnzwithazee.com/dns/forwarding.md#diagnose-an-upstream).

## More specific guides

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


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