network-troubleshooting

Network Troubleshooting

"It's not connecting" describes a symptom, not a cause, and the cause could be any of six or seven layers between the client and the application. The single biggest time-waster in network troubleshooting is guessing at the application layer first because it's the most familiar, when the fault is actually two layers down in DNS or routing. Working through the stack in order — resolution, then reachability, then the port, then the protocol, then the application — turns a guessing session into a bounded diagnosis.

Isolate the layer before you fix anything; a fix aimed at the wrong layer just adds noise to the next person's investigation.

For a symptom-driven command cookbook (dig, curl, traceroute, ss, tcpdump), read references/diagnostic-commands.md.

1. Confirm DNS resolves to what you expect before touching anything else

If the name doesn't resolve, or resolves to the wrong address, nothing past this point matters. dig gives more control and cleaner output than nslookup for this — use it against both the system resolver and the authoritative server directly to separate a propagation issue from a wrong record.

dig +short api.example.com                # what the system resolver returns
dig +short api.example.com @8.8.8.8       # bypass local cache, check a public resolver
dig api.example.com NS                    # who is authoritative

• A mismatch between the two queries above means propagation lag or a stale local cache, not a wrong record — see dns-management for TTL behavior.
• NXDOMAIN from the authoritative server itself means the record genuinely doesn't exist; stop looking downstream and fix the zone.

Done when: the resolved address is confirmed correct from both the client's resolver and the authoritative source, or the mismatch is understood and explained.

2. Confirm reachability and the path before assuming a firewall

Once the address is right, check whether packets can get there at all, and where they stop if not. traceroute (or mtr for a continuously updating view with loss percentages) shows each hop; a consistent stop at the same hop across repeated runs points at that hop specifically, not at the destination.