network-troubleshooting

Network Troubleshooting

Purpose

Isolate a network failure to a specific layer instead of guessing. Nearly every network problem is DNS, TLS, a firewall, or a timeout — and each has a distinct signature that identifies it in seconds.

When to Use

• Connection refused, connection reset, or timeouts.
• TLS handshake and certificate errors.
• DNS resolution failures, including intermittent ones.
• "It works from my machine but not from the cluster."
• Intermittent failures under load.

Capabilities

• Layer-by-layer isolation: DNS, TCP, TLS, HTTP.
• Tooling: dig, nc, openssl s_client, curl -v, ss, tcpdump.
• Cloud-specific diagnosis: security groups, NACLs, route tables, service meshes.
• Connection-pool and ephemeral-port exhaustion.
• MTU and path-MTU problems.

Inputs

• The exact error message and the client that produced it.
• Where it fails from and where it succeeds from.
• Whether it is consistent or intermittent — this distinction matters more than any other.

Outputs

• The failing layer, identified with evidence.
• The fix, and confirmation that the path now works from the failing location.

Workflow

1. Read the error precisely — "Connection refused" means something is listening but rejecting, or nothing is there and the host answered. "Timeout" means nothing answered at all — usually a firewall dropping packets silently. These have completely different causes.
2. Resolve the name — dig +short host. If DNS is wrong or slow, nothing downstream matters. Check the resolver being used, not just your laptop's.
3. Open a socket — nc -vz host port. This separates "the network path is blocked" from "the application is broken", which is the single most valuable distinction available.
4. Complete the handshake — openssl s_client -connect host:443 -servername host. Certificate chain, expiry, and SNI problems all surface here.
5. Make the request — curl -v. Now, and only now, are you debugging the application.
6. For intermittent failures, look at exhaustion — Connection pools, ephemeral ports, conntrack tables, and DNS caches. Intermittent almost always means "a limit is being hit under load".