Before connecting by name, a client usually needs an IP address. If that step fails, the application itself may still be healthy. Check the name, record type and DNS server being queried.
Inspect the system view
getent hosts uses the system name-resolution mechanisms, including /etc/hosts and NSS settings. dig sends a DNS query. Their answers can differ because they exercise different paths.
getent hosts api.example.test
cat /etc/resolv.conf
dig api.example.test Aexample.test is a placeholder. When troubleshooting, use the name from the application error.
Read the response status
NXDOMAIN reports a non-existent queried name. SERVFAIL reports a failure while processing the query. A timeout is different: no response arrived in time. Inspect the full output rather than only +short.
dig @10.0.0.53 api.example.test A +time=2 +tries=1;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 4102An explicit @server tests the intended resolver. Replace 10.0.0.53 with your training DNS address.
Compare resolution and connectivity
If a trusted source provides the IP, curl --resolve tests that server while retaining the original URL hostname. This temporarily bypasses DNS for diagnosis; it does not repair resolver settings. HTTPS keeps the hostname for TLS.
curl -sS -i --max-time 5 --resolve api.example.test:80:10.0.0.20 http://api.example.test/healthIf this works, return to DNS and inspect configuration, resolver reachability and records. After the fix, repeat the request without --resolve.
Inspect the path to the resolver
The payment case’s DNS move and network hardening suggest different hypotheses. If the intended resolver never answers, inspect addresses, routes and access rules rather than substituting a hosts entry. ICMP may work while DNS traffic is blocked.
DNS uses both UDP and TCP. Comparing ordinary dig with dig +tcp can narrow the failing boundary. Different results do not justify removing the whole firewall; identify the specific resolver rule and direction.
ip route
dig @10.0.0.53 gateway.pay.internal A +time=2 +tries=1
dig @10.0.0.53 gateway.pay.internal A +tcp +time=2 +tries=1Replace the example resolver address with the one in your environment, then verify the normal named payment request.
From symptom to check
| Observation | Next check | How to interpret it |
|---|---|---|
| NXDOMAIN | Full name and selected DNS server | The response describes the name in this DNS context; inspect the query and zone. |
| UDP dig times out; +tcp answers | UDP reachability to the resolver | Separate transport filtering from the DNS answer itself. |
| dig answers, getent cannot resolve | NSS, hosts and the system resolver | The application’s system path differs from a direct DNS query. |
Common mistakes
- Treating a successful ping as a DNS transport test.
- Removing all firewall rules instead of isolating the relevant one.
- Keeping a hosts workaround instead of repairing resolution.
How to prove recovery
- Check getent for the name payments uses.
- Check the configured DNS path without a diagnostic bypass.
- Call the normal named payment business route.
- Preserve required network policy while fixing the specific failure.
MINI INCIDENT
The gateway is alive, but payments fail
HTTP works to a known IP, getent cannot resolve the name, and UDP dig to corporate DNS hangs. dig +tcp answers. Where should you investigate, and why not edit the application first?
HTTP to known IP: 200
DNS UDP: timeout
DNS TCP: answer receivedExplore the diagnosis
Compare the UDP path and resolver rules, then repeat system resolution. The observations isolate a DNS transport difference without identifying a specific rule. The application may simply be receiving a resolution failure.
WORKSHOP
Workshop: explain the evidence and choose an action
The same name was tested using system lookup, DNS and a direct bypass. Explain what each observation covers.
getent api.example.test → 10.0.0.19
dig api.example.test A → 10.0.0.20
--resolve ...:10.0.0.20 → application 200Which hypothesis explains the different addresses?
Compare your reasoning
System lookup can use /etc/hosts and other sources besides DNS. Compare lookup order and configuration rather than declaring DNS broken from getent alone.
What does the --resolve bypass establish?
Compare your reasoning
The application is reachable at that address while preserving the request name. This narrows the investigation but does not repair ordinary client name resolution.
How can verification finish without a permanent bypass?
Compare your reasoning
Repair the verified source of disagreement, then repeat getent and a normal named request from the original context. A diagnostic address must not remain the only working access path.
CHECK YOUR UNDERSTANDING
dig +short printed nothing. Does that prove the name does not exist?
Show explanation
No. Short output hides the status. Inspect the full response: NXDOMAIN, SERVFAIL, a missing record type and a timeout require different actions.
No comments yet. Share your first impression or ask a question about this topic.