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.