# Diagnose Docker DNS failures when the VPS resolves names correctly

Your VPS can resolve a database hostname, but an application container reports `EAI_AGAIN`, `UnknownHostException` or “could not resolve host”. Containers have their own network context. A successful lookup on the host does not test the application's resolver path.

## 1. Separate external names from service names

Record the exact failing name. A public hostname such as `example.com` and a Compose service name such as `database` are different tests. Public DNS cannot fix a missing private service alias. Run diagnostics only on containers and networks you administer; on managed game hosting, provide the evidence to support instead of attempting Docker access.

## 2. Compare the same name in both places

Replace `APP_CONTAINER` with the existing container name. These commands use utilities already present; a minimal image may not include `getent` or `cat`. A missing command says nothing about DNS health. Do not install packages into a production container just to complete this checklist.

```
getent ahosts example.com
docker exec APP_CONTAINER getent ahosts example.com
docker exec APP_CONTAINER cat /etc/resolv.conf
```

Compare the returned addresses and any delay. Different address order can be normal. Repeated failure only inside the container narrows the investigation. If DNS succeeds there but the application still times out, inspect its destination port, TLS configuration and connection pool instead.

## 3. Understand the resolver address

Docker's user-defined networks use an embedded resolver, normally shown as `127.0.0.11`. That address is expected. In contrast, a manually configured resolver at `127.0.0.1` points at the container itself, not a DNS service on the VPS. Default bridge networking and host networking behave differently, so identify the network mode before applying advice intended for another setup.

```
docker inspect --format '{{.HostConfig.NetworkMode}} {{json .HostConfig.Dns}}' APP_CONTAINER
docker inspect --format '{{json .NetworkSettings.Networks}}' APP_CONTAINER
```

## 4. Check service discovery and upstream access separately

If public names work but a database service name fails, compare the two containers' network membership and the configured service alias. They need a network where that name is defined. If private names work but external names fail, review resolver overrides in the deployment configuration and Docker daemon logs around the incident.

Do not publish a full `docker inspect` dump: environment variables may contain credentials. Avoid replacing all resolvers with a public DNS address, which may make internal names unavailable. DNS traffic can use both UDP and TCP; a firewall that permits only one can cause selective failures.

## Verify without a disruptive restart

Repeat the same lookup several times and then make one normal application connection. Fix deployment configuration through the service's normal maintenance process, preserving its volumes and rollback information. Do not delete the container or restart the Docker daemon as an initial test. Send support the container name, network mode, failing hostname, timestamps and redacted resolver output if the forwarding path remains uncertain.

Related: [review Docker port exposure](https://help.cloudexa-hosting.com/books/vps-dedicated-servers/page/check-which-docker-ports-are-exposed-publicly) and [protect Docker volumes before changes](https://help.cloudexa-hosting.com/books/vps-dedicated-servers/page/preserve-docker-volumes-before-updating-a-container).

## Official references

- [Docker DNS services and network modes](https://docs.docker.com/engine/network/)
- [Docker daemon DNS troubleshooting](https://docs.docker.com/engine/daemon/troubleshoot/)
- [Docker inspect command](https://docs.docker.com/reference/cli/docker/inspect/)