DNS debugging methodology

Topic: Networking basics

When resolution fails, isolate the problem: check local resolver config, then query a specific server, then check network path to the server. Use dig, getent, and nslookup in a consistent order so you know whether the issue is config, server, or network. Use this when name resolution fails and you need to find the cause quickly.

Intent: Troubleshooting

Quick answer

  • Step 1: getent hosts example.com (uses system resolver). If this fails, the problem is local config or the resolver the system is using. Step 2: dig @8.8.8.8 example.com (bypass local resolver). If this works, fix local resolver config; if it fails, the problem may be network or the name itself.
  • Step 3: dig @RESOLVER_IP example.com with the resolver from resolv.conf. If getent fails but dig @8.8.8.8 works, the resolver in resolv.conf is wrong or unreachable. If dig @RESOLVER works, the system is not using it (stub resolver, nsswitch, or wrong resolv.conf).
  • Check /etc/resolv.conf, /etc/nsswitch.conf (hosts: files dns), and whether systemd-resolved or another stub is in use. Fix the source that manages resolv.conf (netplan, NetworkManager, resolved) so the right nameservers are used.

Prerequisites

Steps

  1. Test system resolver

    getent hosts example.com. If it fails, the system resolver (resolv.conf, nsswitch, stub) is wrong or the resolver it uses is unreachable or returning failure.

  2. Test direct query

    dig @8.8.8.8 example.com. If this works, the problem is local: wrong resolv.conf, unreachable resolver, or stub resolver not forwarding. If this fails, the issue may be network (no route to 8.8.8.8) or the name (NXDOMAIN).

  3. Test configured resolver

    dig @RESOLVER_IP example.com where RESOLVER_IP is from resolv.conf. If this works but getent fails, the system is not using that resolver (check nsswitch, resolved, or netplan).

  4. Fix the right layer

    Wrong nameserver in resolv.conf: fix netplan, NM, or resolved. Resolver unreachable: fix route or firewall (UDP/TCP 53). Stub not forwarding: fix resolved or nsswitch. Document the fix so it persists.

Summary

Debug DNS in order: getent (system resolver), then dig @8.8.8.8 (bypass local), then dig @your-resolver. Use the result to fix config, resolver reachability, or network. Use this when resolution fails so you fix the right layer.

Prerequisites

Steps

Step 1: Test system resolver

Run getent hosts example.com. Failure means system resolver or its upstream is wrong or unreachable.

Step 2: Test direct query

Run dig @8.8.8.8 example.com. Success means the problem is local config or resolver reachability; failure may be network or the name.

Step 3: Test configured resolver

Run dig @RESOLVER_IP example.com. If it works but getent fails, the system is not using that resolver (stub, nsswitch, or wrong resolv.conf).

Step 4: Fix the right layer

Fix resolv.conf source, resolver reachability, or stub/nsswitch as indicated by the tests. Document the fix.

Verification

You can isolate DNS failure to config, resolver, or network and apply the correct fix.

Troubleshooting

getent works, app fails — App may use a different resolver (e.g. Go resolver, custom); check app config. dig works, getent fails — Stub resolver (resolved) may be overriding; fix resolved or point resolv.conf to the desired resolver.

Next steps

Continue to