DNS Troubleshooting: Trace Name Resolution Before Blaming the Network
Separate resolver configuration, caching, search domains, authoritative records, and application-level DNS behavior.
On this page
Confirm the name and resolver path
When a service cannot reach api.internal, first establish which machine, container, or runtime is resolving the name. Inspect /etc/resolv.conf, search domains, and resolver configuration in the actual network namespace. A developer laptop and a Kubernetes pod may ask different resolvers and apply different suffixes.
Use getent hosts name to see the system name-service result, and use dig or nslookup to query DNS records directly. These tools test different layers: a direct DNS query can work while the application's configured resolver path, NSS module, proxy, or runtime cache behaves differently.
Follow the record chain
Check the record type the application needs: A/AAAA for addresses, CNAME for aliases, and SRV for service discovery. A missing IPv6 route can make an AAAA result appear broken even while IPv4 works. Inspect TTLs and authoritative answers when changes seem inconsistent; caches may retain old values until expiration.
Search domains can transform a short hostname into several candidate names. A typo may therefore resolve to an unexpected internal host rather than fail cleanly. Prefer fully qualified names in production configuration when ambiguity is costly.
Separate DNS from connection failure
Once you know the resolved address, test route and transport separately. If DNS returns the expected IP but TCP connection times out, investigate routing, firewall policy, listener state, or load-balancer health. If DNS lookup itself stalls, capture resolver traffic and check UDP/TCP port 53, retries, packet loss, and resolver availability.
Applications can cache DNS results independently of system TTL behavior. Long-lived runtimes and connection pools may keep sockets to old addresses even after DNS changes. Restarting everything can temporarily hide the issue; inspect application resolver and pool behavior before using restarts as a fix.
Root-cause checklist
- Reproduce from the same container, host, and namespace as the failing process.
- Record the exact queried name, record type, resolver, answer, and TTL.
- Compare system resolver output with a direct authoritative query.
- Test the resolved address and port independently of name resolution.
- Check IPv4/IPv6 selection, search suffixes, and local caches.
- Confirm application DNS caching and connection-pool lifetimes.
DNS debugging becomes much faster when “name lookup failed” is separated from “the name resolved but the connection failed.”