Linux: Troubleshoot DNS problems systematically
When a host name fails, “DNS is broken” is not yet a diagnosis. This sequence separates local resolver configuration, system name resolution and a DNS query, and shows what each result actually proves.
1. Inspect local network and DNS configuration
Start on the affected device while the issue is occurring. The admin-tools Linux diagnostic reads interface addresses with ip -j address show and then runs resolvectl status. This can show active links, assigned DNS servers and, where configured, search or routing domains.
ip -j address show resolvectl status
resolvectl belongs to systemd-resolved and is not present or active on every distribution. If the command is missing, the project check reads /etc/resolv.conf instead:
cat /etc/resolv.conf
The file may be static, generated by NetworkManager or another network tool, or point to a local resolver stub. It therefore may not show the complete path to the upstream DNS server. Rely on resolvectl details only when systemd-resolved is in use; DNS routes can vary by connection, distribution and VPN.
Do not change anything yet
An unexpected DNS server or empty output is a clue, not proof of the cause. Do not overwrite /etc/resolv.conf or restart a service until you know which network tool manages the configuration.
2. Distinguish system resolution from a DNS query
First check the system path: getent
getent ahosts service.example
getent uses the name-resolution path configured by the system. On glibc systems this follows the NSS rules in /etc/nsswitch.conf: an answer may come from /etc/hosts, DNS, a local systemd-resolved stub or another configured source. Success therefore does not prove that a DNS server was contacted. On failure, getent often gives fewer diagnostic details than a DNS tool.
Then query the DNS resolver directly: dig
dig +time=3 +tries=1 service.example A
dig asks the DNS server from the resolver configuration for an A record. It bypasses NSS selection and /etc/hosts, but without an explicit server argument it still uses the configured resolver. This is the direct DNS query in the Linux catalogue; querying an arbitrary server is not part of that check. If dig is missing, the diagnostic tries nslookup -timeout=3 service.example. If both tools are absent, the result is “unavailable”; do not install anything just to follow this guide.
Protect internal names
Do not send internal host names or search domains to public DNS servers as a test. Split DNS and VPNs may intentionally return different answers. Compare only with approved targets and follow your organisation’s rules.
3. Interpret output and error messages
This entirely fictional output uses only documentation addresses from 192.0.2.0/24. service.example and the values are examples, not real internal systems or user data:
$ getent ahosts service.example 192.0.2.42 STREAM service.example $ dig +time=3 +tries=1 service.example A ;; ->>HEADER<<- opcode: QUERY, status: NOERROR ;; ANSWER SECTION: service.example. 60 IN A 192.0.2.42
| Result | Meaning and next step |
|---|---|
| NOERROR with an answer | The requested record type received an answer in the DNS namespace used. This proves neither that the service is reachable nor that every application uses the same resolver path. |
| NOERROR without an answer | The name may exist but have no record of the requested type (NODATA). Compare A and AAAA before concluding that the name does not exist. |
| NXDOMAIN | The queried DNS namespace reports that the name does not exist. Check spelling, search domain and whether the correct VPN or internal DNS context is active; it does not automatically mean the DNS service is down. |
| SERVFAIL | The resolver could not complete the query. An upstream, delegation or validation problem may be involved; the status alone does not identify the cause. |
| REFUSED | The server refuses the query under its policy. Check whether this client and name are intended to use that resolver. |
| Timeout / no servers could be reached | No usable DNS response returned. First check the configured resolver, local route and filtering, and VPN connection; a timeout alone proves neither a DNS-server fault nor a general network outage. |
| getent returns no result | This only shows that system resolution returned no result. A hosts entry, NSS order, missing tools or a different search path may explain a difference from dig. |
4. Continue troubleshooting in this order
- Record the target and time. Note the host name, application, network/VPN and whether the issue is happening now. Do not put real internal names in a public ticket.
- Inspect configuration. Run ip -j address show and, if available, resolvectl status. If resolvectl is missing, cat /etc/resolv.conf shows only the local resolver file, not necessarily all dynamic rules.
- Test system resolution. getent ahosts service.example checks the path used by typical system applications. No result is a reason to compare directly, not a root cause by itself.
- Check the DNS response separately. Run dig +time=3 +tries=1 service.example A; if dig is missing, use nslookup -timeout=3 service.example. Compare status and record type, not only the exit code.
- Separate resolution from reachability. If the name resolves but the application fails, investigate routing, firewall, TCP port, service or application next. A ping to a numeric address—available as a separate Linux check—tests ICMP, not the application port; no ping reply may also be caused by ICMP filtering.
- Compare with a working device. The same name, record type, connection and time help distinguish client-specific differences from site, VPN or resolver differences. Every probe remains a snapshot.
What the results do not tell you
- A DNS cache that cannot be queried portably on Linux is not a fault by itself. Linux installations use different resolvers and cache services, so the diagnostic catalogue marks a portable cache listing as unavailable. Missing cache output does not mean name resolution is absent or broken.
- resolvectl, dig, nslookup and getent are not present on every installation. The existing Linux diagnostic falls back from resolvectl to /etc/resolv.conf and from dig to nslookup; if the alternative is also missing, the check is marked unavailable.
- A successful DNS record does not prove TCP reachability; a failed ping does not prove a DNS fault. DNS caches, local hosts entries, split DNS, search domains, IPv4/IPv6 and application settings can produce different answers.
- Error text and status labels differ between dig and nslookup and across distributions. Missing tools, restricted permissions or unmanaged resolvers can leave the output incomplete.
The Linux information page describes the checks that are actually available and their requirements. Its linked sample result contains static, fictional values only and does not run a diagnosis.
Sources and command basis
Commands and fallbacks follow this project’s Linux check catalogue and runner. Their general meaning is based on the relevant manual pages and documentation: