Connectivity Triage

Connectivity Triage

Localize an active connectivity failure without changing network configuration. Collect the smallest useful evidence set, distinguish observations from inference, and stop when the fault domain is clear enough for the next safe action.

When to Use This Skill

Use this workflow when a macOS endpoint has an active symptom such as:

• an API, website, or MCP service timing out or disconnecting;
• DNS lookup failures or inconsistent name resolution;
• packet loss, latency, or unstable interactive traffic;
• an application that appears offline while other traffic works;
• uncertainty about whether the problem is local, upstream, or at the service.

This is a diagnostic workflow, not a remediation workflow. Do not change interface state, DNS settings, VPN/firewall configuration, or remote service state while establishing the fault domain.

Fast Decision Flow

Work from the symptom toward the narrowest discriminating check:

symptom
  -> local link / LAN evidence
  -> DNS configuration and resolution
  -> destination reachability
  -> path quality
  -> application / service timing
  -> fault-domain assessment

Stop early when the evidence is already sufficient. Do not run every probe mechanically.

1. Define the symptom

Record the affected application or process, destination hostname or URL, when the failure started, whether it is continuous or intermittent, and whether unrelated destinations still work.

If the symptom is application-specific, preserve the exact hostname or URL the application uses. Testing an unrelated public site can establish general connectivity but cannot prove the affected service is healthy.

2. Check local-link / LAN evidence

When available, run a bounded networkQuality sample for a broad responsiveness and throughput signal. If networkQuality is unavailable, continue; it is optional.

If a known local gateway or same-LAN target is available, compare a short bounded ping sample to that local target with a short sample to the remote destination. Do not invent a gateway address. If no local target is known, leave the LAN segment unproven and continue.

Useful pattern:

ping -c 5 <known-local-target>
ping -c 5 <destination>

3. Separate DNS configuration from DNS behavior

Inspect the system resolver state, especially when VPNs, split DNS, or scoped resolvers may be involved:

scutil --dns

Then test the destination name directly with a bounded DNS query:

dig +time=2 +tries=1 <hostname>

Treat these as different evidence. scutil --dns shows resolver configuration; dig shows query behavior. A successful lookup does not prove the returned endpoint is reachable.

4. Test reachability and path quality

Use a short ping sample when ICMP is a useful signal:

ping -c 5 <destination>

If the hostname resolves, test the returned address separately only when doing so helps distinguish DNS behavior from path failure. If resolution currently fails, use an address only when it was previously observed from trustworthy incident evidence; otherwise leave address-level reachability unknown.

Use a bounded numeric traceroute when path visibility would reduce uncertainty:

traceroute -n -q 1 -m 20 <destination>

A silent or changing hop is an observation, not proof that the hop is broken. Routers may filter or rate-limit traceroute traffic while forwarding application traffic normally.

5. Inspect the affected application's live network activity

When the problem is process-specific, use a bounded nettop capture rather than watching indefinitely:

nettop -n -L 3 -p <process-name-or-pid>

Use it to confirm whether the process is opening connections, which endpoints it is using, and whether traffic is flowing. Lack of visible activity may mean the application never attempted the connection; it does not by itself identify why.

6. Time the application path

For HTTP(S), use curl phase timing against the actual affected endpoint when a safe read-only request is available. Confirm the incident-supplied endpoint is a complete http:// or https:// URL, preserve its original scheme, and pass the URL as one quoted argument rather than interpolating arbitrary incident text into the shell command:

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  --connect-timeout 5 --max-time 15 '<affected-http-or-https-url>'

Interpret the phases comparatively. High time-to-first-byte can include server processing, so it is not proof of network latency.