Network Troubleshooting

Network issues are common; the symptoms vary; the actual cause is often somewhere unexpected. The systematic approach: narrow down where in the network the problem is, before guessing at fixes.

This page covers the diagnostic toolkit and the workflow.

The systematic approach

When a network problem appears:

  1. Reproduce: confirm the issue. Does it happen reliably or intermittently?
  2. Narrow scope: client problem? Network path? DNS? Server?
  3. Tools per layer: each layer has tools to test it
  4. Fix at the right layer: don't fix server when DNS is the problem

Layer-by-layer tools

DNS

dig example.com
nslookup example.com
host example.com

dig is the most flexible:

dig example.com           # A record
dig example.com AAAA      # IPv6
dig example.com MX        # mail
dig +trace example.com    # show full resolution path
dig @8.8.8.8 example.com  # specific resolver

If DNS doesn't resolve, that's the problem. If it resolves but to wrong IP, propagation or config issue.

Reachability

ping <host>
ping6 <host>  # IPv6

Basic round-trip test. If ping fails, host is unreachable or filtering ICMP. Many cloud networks block ICMP.

ping doesn't test application — just basic IP connectivity.

Path

traceroute <host>
mtr <host>     # combines ping + traceroute, continuous

Shows each hop. Useful for identifying where packets are lost or delayed.

mtr is more useful than traceroute for ongoing debugging — refreshes continuously.

Port reachability

nc -zv <host> <port>     # check if port is open
telnet <host> <port>     # interactive
nmap -p <port> <host>    # more thorough

If port unreachable: firewall, security group, or service not listening.

TCP details

ss -tnp                  # active connections
ss -tlnp                 # listening sockets
ss -s                    # summary
netstat -an | grep ESTAB # legacy version

Shows what's connected to what. Important for diagnosing connection-pool issues, port exhaustion, etc.

HTTP

curl -v https://example.com
curl -I https://example.com    # headers only
curl --resolve host:80:1.2.3.4 ...   # override DNS

Verbose curl shows the full TLS handshake, headers, response. For HTTP-level issues, this is the workhorse.

curl --trace-ascii out.txt ...  # full trace

For deep debugging.

Packet capture

tcpdump -i any -nn host <host>
tcpdump -i any -nn -w capture.pcap host <host>

Capture and analyze. The .pcap file opens in Wireshark for visualization.

For debugging issues that need to see actual packets — TCP retransmits, missing handshakes, malformed headers.

TLS

openssl s_client -connect host:443
openssl s_client -connect host:443 -servername sni.example.com

Tests TLS handshake. Useful for cert issues, SNI problems, protocol mismatches.

Common diagnostic flows

"Site is slow"

  1. time curl -o /dev/null https://example.com — total time
  2. curl -w '@curl-format.txt' ... — break down by phase
    • time_namelookup (DNS)
    • time_connect (TCP)
    • time_appconnect (TLS)
    • time_starttransfer (TTFB)
  3. Identify which phase is slow; investigate that

"Can't connect"

  1. dig <host> — DNS works?
  2. ping <host> — IP reachable? (may be blocked)
  3. nc -zv <host> <port> — port open?
  4. curl -v https://<host> — application responds?

If DNS fails, fix DNS. If port closed, fix firewall/security group. If application fails, server-side issue.

"Intermittent failures"

mtr for several minutes. Look for:

Often a network mid-path issue that's not your immediate infrastructure.

"TLS error"

openssl s_client -connect host:443 -showcerts

Examine the cert chain. Common issues:

Cloud-specific tools

AWS

Kubernetes

Containers

Common pitfalls

Different DNS in different places

Local DNS resolver, application DNS cache, VPC resolver — may give different answers.

Caching obscuring problems

Browser cache, CDN cache, DNS cache. When debugging, work to bypass caches.

Logging at the wrong layer

Web server logs don't show network errors. Application logs may not show TLS issues. Look at the right place for the right symptom.

Time differences

Client clock vs. server clock matters for TLS (cert validity windows, JWT expiration).

MTU issues

Fragmented packets through tunnels. Ping with -M do -s 1472 to test path MTU.

Common failure patterns

Further Reading