debugging-network-issues

This skill applies falsification-first methodology to network and streaming incidents where the obvious cause is likely a red herring. Rather than stacking assumptions, it guides you through layered isolation—testing the same request across different paths to pinpoint exactly which hop (client, CDN, proxy, or backend) is responsible. Use it for connection resets, SSE stalls, fixed-time drops, certificate errors, or LAN mysteries where symptoms like "works sometimes" or "fails after N seconds" point to multiple possible layers.

Debugging Network Issues uses evidence-driven layered isolation to pinpoint network, streaming, and protocol bugs where symptoms mask the true cause.

AI-generated summary based on this skill's SKILL.md

★ 1,299 ⁮ 210 MIT updated 2026-07-27 by daymade

Install

daymade/claude-code-skills/debugging-network-issues · repository language: Python

Manual (git clone) CLI (skillfed)

git clone https://github.com/daymade/claude-code-skills
cp -r claude-code-skills/debugging-network-issues ~/.claude/skills/debugging-network-issues

npx skillfed install daymade/claude-code-skills/debugging-network-issues

Frequently asked questions

AI-generated answers based on this skill's SKILL.md and metadata

What is debugging-network-issues and when should I use it?

debugging-network-issues applies falsification-first methodology to network and streaming incidents where the obvious cause is likely wrong. Use it when you face connection resets, SSE stalls, fixed-time drops, certificate errors, or LAN mysteries—especially when symptoms like "works sometimes" or "fails after N seconds" suggest multiple possible layers. Rather than stacking assumptions, it guides you through layered isolation to pinpoint exactly which hop (client, CDN, proxy, or backend) is responsible.

How do I distinguish upload timeout from backend processing timeout for large requests?

debugging-network-issues helps you separate these by testing the same request across different paths. Check reverse proxy access logs for bytes_read to see if the full body arrived; if it did but the response timed out, the backend is slow. If bytes_read is incomplete or the connection drops mid-upload, the upload itself is timing out. Test the same payload via direct connection, then through your CDN or proxy, to isolate which layer is enforcing the timeout.

What does connection reset ECONNRESET debugging involve?

debugging-network-issues guides you to apply layered isolation: test the same request from different clients (direct, VPN, proxy, different network), to different endpoints (direct backend, CDN, reverse proxy), and capture packets at each hop. If ECONNRESET happens only through one path, that hop is responsible. Check for idle timeouts, certificate mismatches, or proxy rules. Use packet capture to see whether the RST comes from your client, the proxy, CDN, or backend.

How can I resolve client-side proxy or VPN misrouting and CNAME rule conflicts?

debugging-network-issues recommends testing the same request with and without your proxy/VPN enabled, and inspecting DNS resolution to confirm the CNAME is resolving to the expected IP. Check your proxy's rule override settings and verify that SSL certificate verification isn't failing due to hostname mismatches. Use packet capture or a network analyzer to confirm which IP your traffic is actually reaching, then compare against your CNAME rule configuration.

How do I identify unknown LAN devices and diagnose subnet topology changes?

debugging-network-issues suggests scanning your LAN for mystery IPs and MAC addresses using ARP tables or network discovery tools. When topology changes cause connection drops at fixed intervals, check for DHCP lease expirations, gateway failovers, or TUN DNS hijacking. Correlate device appearance/disappearance with symptom timing. If getaddrinfo stalls, a resolver on your LAN may be misconfigured; test DNS directly against your gateway and upstream resolvers separately.

What is the core methodology behind debugging-network-issues?

debugging-network-issues uses falsification-first methodology: instead of assuming the obvious cause, you systematically test each layer in isolation. For each symptom, vary one factor at a time—client, path, endpoint, or timing—and record which combinations fail. This layered isolation experiment setup reveals which hop is actually responsible. By falsifying assumptions rather than confirming them, you avoid chasing red herrings and reach the true root cause faster.

SKILL.md

rendered from the published skill — quoted content, verbatim