debugging-network-issues

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared3 observations
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

3. **Credentials or access you do not have** — a management password that exists only on a device label.

- `curl -x http://127.0.0.1:<port> -I https://<host>`

- Resolve the host yourself (DoH), then `curl -x http://127.0.0.1:<port> -k -H 'Host: <host>' -I https://<ip>`

AGENTS.md

Observation: `curl -x http://127.0.0.1:<proxy-port> https://<auth-domain>` returns `SSL_ERROR_SYSCALL` after the proxy tunnel is established.

curl -sS -x http://127.0.0.1:<proxy-port> \

| A | `curl -x http://127.0.0.1:<proxy-port> -I https://<auth-domain>` | `SSL_ERROR_SYSCALL` |

Audit 0.4.1 · source sha 0f7f7e0023de · 29 Oct 2026Report an issue or request a re-scan

• Publisherdaymade GitHub userOwner of the repository this skill is read from
• Source folderdaymade/claude-code-skills/debugging-network-issuesThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict0f7f7e0023deA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Investigates network, streaming and protocol failures with falsification-first layered experiments, the general fallback for unknown root causes. Use for ECONNRESET / RST_STREAM / SSE stalls, CDN/CGNAT timeouts or…

---
name: debugging-network-issues
description: >-
  Investigates network, streaming and protocol failures with falsification-first layered
  experiments, the general fallback for unknown root causes. Use for ECONNRESET / RST_STREAM / SSE
  stalls, CDN/CGNAT timeouts or certificate errors, throughput collapse where everything returns 200
  but transfers crawl, or LAN identity/topology mysteries. Not for known
  Tailscale/TUN/DNS/proxy-path conflicts (use tunnel-doctor).
---

# Debugging Network Issues

Evidence-driven investigation methodology for incidents where the obvious cause is probably wrong. Built from a real 5-hour production case (see [references/case-sse-rst-130s.md](references/case-sse-rst-130s.md)) where assumption-stacking wasted hours that a 10-minute layered experiment would have resolved.

Apply this skill when the user reports a network/streaming/protocol symptom and the investigator feels tempted to diagnose from one log line or one circumstantial data point. The skill's job is to slow that reflex down.

## Triage first — is this a known domain?

Before applying the general methodology below, check whether the symptom points at a stack that already has a dedicated skill in this repo. Those carry the domain-specific symptom→cause→fix tables this skill deliberately stays general about — start there, and come back here for methodology if the root cause turns out to be elsewhere.

| If the symptom is...                                                                                                                                                                                       | Start with                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| macOS Tailscale ⨯ proxy/VPN conflict (Shadowrocket / Clash / Surge): `tailscale ping` works but SSH/curl/git fails, `Connection closed by 198.18.x.x`, TUN DNS hijack, ~60s `getaddrinfo` resolver stall | **tunnel-doctor**                            |
| Cloudflare config: `ERR_TOO_MANY_REDIRECTS`, SSL-mode mismatch, DNS / proxy-status issues behind the orange cloud                                                                                        | **cloudflare-troubleshooting**               |
| Windows App / AVD / W365 RDP connection quality: WebSocket instead of UDP Shortpath, high RTT, STUN/TURN interference                                                                                    | **windows-remote-desktop-connection-doctor** |
| Client-side proxy / VPN / TUN misrouting: one specific site fails with `ERR_CONNECTION_CLOSED` or `SSL_ERROR_SYSCALL`, other sites work, DNS returns fake/TUN IPs, and adding a PROXY rule did not help | **this skill** — read [references/case-proxy-tun-cname-override.md](references/case-proxy-tun-cname-override.md) first |
| TLS certificate-verification errors (`UNKNOWN_CERTIFICATE_VERIFICATION_ERROR`, a cert for the wrong site) or mid-handshake EOFs on **every** DIRECT-routed/domestic domain at once, while proxied domains work — and any proxy health watchdog still reports green                                        | **tunnel-doctor** (TUN DIRECT split-brain step) |
| The proxy is reachable and the OS/Tailscale route is healthy, but bulk transfers are slow and changing the active exit/node changes the measured rate | **tunnel-doctor** — proxy node / exit / chain capacity branch |
| **Nothing errors — it is just slow.** Every request returns 200, latency and health checks look fine, but transfers crawl, bulk jobs overrun their estimates, or files arrive truncated | **this skill** — go straight to [Step 0.7](#step-07-throughput-collapse--when-nothing-errors-and-everything-is-slow); the error-driven steps have nothing to bite on |
| A whole group of smart-home / IoT devices is offline at once — often weeks after a router/AP swap or Wi-Fi settings change; the hub is "right there" but its children are all dead, plus some direct-Wi-Fi devices | **this skill** — read [references/case-iot-router-migration-wpa3.md](references/case-iot-router-migration-wpa3.md) first |

If none match — or you tried a domain skill and the evidence points elsewhere — continue below. The methodology generalizes to any multi-layer system.

> **Note for this skill specifically**: If the symptom is a Cloudflare 524/522 on a **large `POST` body** (e.g., `/<openrouter-path>` with `Content-Length` > 1 MB), the failure is often **upload time to origin exceeding Cloudflare's origin read timeout**, not backend slowness. Use the upload-vs-processing checklist below before assuming a backend stall.

## Core principles

### 1. Evidence over assumption

If you cannot point to a concrete artifact — log line, pcap frame, probe output, metric sample — you are guessing, not diagnosing. Before stating "X is the cause", require yourself to name the direct evidence. If it does not exist yet, add instrumentation (see [references/instrumentation-patterns.md](references/instrumentation-patterns.md)) or capture it (see [references/packet-capture-recipes.md](references/packet-capture-recipes.md)) before continuing.

### 2. Falsification over confirmation

N independent sources "confirming" a hypothesis does not make it true. One falsifying observation rules it out. Before acting on a hypothesis, answer:

> "What observation would make me abandon this hypothesis?"

If the answer is "nothing" or "I cannot think of one", the hypothesis is unfalsifiable and must not drive the investigation. If the answer is concrete, go look for that observation before committing to action.

### 3. Layered isolation

Multi-hop systems (client → CDN → LB → reverse proxy → app → upstream) concentrate bugs at the seams between layers. When a symptom could plausibly come from several layers, **do not reason about which layer; test**. C

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-29
   ✕BLOCK D 69 / 100

   first audit · source 0f7f7e0023de

Questions about debugging-network-issues

• github.com/daymade/claude-code-skills/tree/main/debugging-networ — the audited source at commit 0f7f7e0023de and every finding aboveObserved · 29 Oct 2026

Spotted something wrong? Report a correction · Methodology