# Debugging Network Issues > >- - **Type:** Skill - **Install:** `agentstack add skill-daymade-claude-code-skills-debugging-network-issues` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [daymade](https://agentstack.voostack.com/s/daymade) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [daymade](https://github.com/daymade) - **Source:** https://github.com/daymade/claude-code-skills/tree/main/debugging-network-issues ## Install ```sh agentstack add skill-daymade-claude-code-skills-debugging-network-issues ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 | 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., `/` 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**. The canonical technique: run the same logical request through three or more paths that differ by exactly one hop, then compare where the symptom appears. This resolves in minutes what stacking hypotheses cannot resolve in hours. See [references/layered-isolation-experiment.md](references/layered-isolation-experiment.md). ### 4. Counter-review before committing Before committing to a root cause or shipping a fix, have independent reviewers challenge the conclusion — not confirm it. Agents are good at surfacing risks a single investigator did not think of; they are bad at weighing them. Apply the four-question filter (see [references/counter-review-pattern.md](references/counter-review-pattern.md)) to every finding before it shapes action. ## Workflow Copy this checklist into the investigation notes and check items off: ``` Investigation Progress: - [ ] Step 0: Scope the symptom (exact error, exact times, who, who-not, what changed) - [ ] Step 0.5: Verify the premise — does direct evidence show the symptom is actually happening? - [ ] Step 0.6: **For large POST bodies: distinguish upload-timeout from processing-timeout** (see recipe below) - [ ] Step 1: Gather direct evidence at every hop before hypothesizing - [ ] Step 2: Frame ≥3 hypotheses; for each, name (a) what falsifies it, (b) which layer boundary the intervention would target - [ ] Step 3: Design a decisive experiment (for network: layered isolation) - [ ] Step 4: Add instrumentation if evidence gaps block direct observation - [ ] Step 5: Execute, record actual vs predicted - [ ] Step 6: Counter-review before acting - [ ] Step 7: Fix + re-run the same experiment to verify - [ ] Step 8: Document wrong turns as teaching material ``` ### Step 0: Scope A tight scope is the difference between a 20-minute investigation and a 5-hour one. Before looking at anything, extract: - **Exact error string** (copy-paste, not paraphrase). `socket closed` is not the same as `ECONNRESET` is not the same as `HTTP/2 RST_STREAM INTERNAL_ERROR (err 2)`. - **Exact timestamps** (ISO-8601 with timezone, not "yesterday evening") - **Reproducibility** (every time / intermittent / only specific users) - **Who is affected, who is not** (differential observations narrow the search) - **What changed recently** (deploys, config, upstream dependencies, client versions) Distinguish symptom from diagnosis. "Slow" is not a symptom. "Request took 130.898s then returned HTTP/2 INTERNAL_ERROR" is. ### Step 0.5: Verify the premise Before investing in a full investigation, confirm the reported symptom is actually happening — not just inferred from downstream effects or user frustration. One cheap direct observation beats hours spent investigating a non-problem. Ask: **"What direct evidence shows this symptom is real?"** - If the user reports "timeout at 130s": is that from a timestamped log, a browser network panel, or a recollection? - If the user reports "connection reset": did they see the packet or is it inferred from a retry spike? - If the user reports "fails for some but not others": has it been reproduced in a controlled test, or is it anecdotal? Acceptable premises: - Log line with timestamp and error string - Browser DevTools Network screenshot showing the failure - Reproduction command that shows the symptom on demand - Metrics chart showing the specific error count rising Not sufficient as premise: - "Users are saying it feels slow" - "The alert fired but I did not check what actually failed" - "Last week someone mentioned..." If the premise fails verification, the fix is observation — not investigation. Add the missing telemetry, wait for the next occurrence with instrumentation in place, and return when you have real data. Resist the sunk-cost instinct to investigate anyway "since we are already here". ### Step 0.6: Upload-timeout vs processing-timeout for large POST bodies For CDN-fronted `POST`/`PUT` endpoints with large bodies, the most common misdiagnosis is blaming backend slowness when the real problem is **time-to-upload-body exceeding the CDN/proxy origin timeout**. Apply this sub-checklist when the symptom is a 524/522/504 on a request with `Content-Length > ~500 KB`: 1. **Locate the edge/reverse-proxy access log** (Caddy, nginx, Envoy, Cloudflare Logpush). 2. **Compare `bytes_read` (or equivalent) to `Content-Length`**: - `bytes_read == Content-Length` and `status` is an error → likely backend/processing problem. - `bytes_read / app `request_time` = time backend spent processing after body was fully received. - If proxy `duration` ≈ timeout but upstream `request_time` is short or never logged, the body upload is the bottleneck. 4. **Look for `status=0` (Caddy) or `-` (nginx)**: - `status=0` means the proxy never wrote an HTTP response, usually because the downstream/client side closed first. 5. **Correlate with upstream logs**: - If the request ID / ray ID / trace ID **does not appear** in upstream (, , app) logs, the request never finished uploading. **Example signature of an upload-timeout 524:** ```json { "status": 0, "duration": 125.0, "bytes_read": 4111422, "request": { "headers": { "Content-Length": ["6042141"] } } } ``` Interpretation: the proxy kept the connection for 125 s, read 4.1 MB of a 6 MB body, then Cloudflare closed it and returned 524. **Example signature of a processing-timeout:** ```json { "status": 504, "duration": 120.1, "bytes_read": 6042141, "request": { "headers": { "Content-Length": ["6042141"] } } } ``` Interpretation: full body uploaded, but backend did not respond before proxy timeout → backend/processing problem. ### Step 1: Gather direct evidence at every hop Before framing hypotheses, collect: - Server-side logs at every hop in the request path - Client-side logs (browser devtools HAR, CLI debug log, SDK traces) - Metrics over the incident window (RPS, latency, error rate, connection count, CPU/mem) - Distributed trace if available - Packet capture if the symptom is at the wire level (see [references/packet-capture-recipes.md](references/packet-capture-recipes.md)) If any of these is missing and relevant, **fill the gap before guessing**. Adding a `TRACE_*` env flag and restarting a container beats an hour of hypothesis-stacking. The instrumentation patterns in [references/instrumentation-patterns.md](references/instrumentation-patterns.md) are low-risk, env-gated, and safe to ship into production permanently. #### Reading reverse-proxy access logs for upload/processing split Caddy and nginx logs are the cheapest way to falsify "backend is slow". Focus on three fields: | Field | Caddy JSON key | nginx var | Meaning | | ------------------- | -------------------------------- | ------------------------- | ------------------------------------------------------------------ | | Total wall time | `duration` | `$request_time` | First byte from client → last byte to client (or connection close) | | Body bytes received | `bytes_read` | `$request_length` (rough) | Bytes the proxy actually read from the client | | Declared body size | `request.headers.Content-Length` | `$content_length` | What the client said it would send | | Response status | `status` | `$status` | `0` / `-` means the proxy never wrote a response | **Key patterns:** - `bytes_read stack (Cloudflare → Caddy → → → ), the canonical trace is: 1. **Cloudflare**: get `Cf-Ray` and timestamp from the client error or Cloudflare Logpush. 2. **Caddy**: `docker logs | grep ` → extract `X-Request-Id` (Caddy `uuid`) and confirm `bytes_read`, `duration`, `status`. 3. ****: `docker logs ` for `Client request error: aborted` or request/response logs. 4. ****: `grep /data//log/access.log` → confirms whether the request reached and how long upstream processing took. 5. ****: `docker logs ` for billing/channel errors. If the request ID never appears in steps 3–5, the failure happened at the edge or during body upload. #### Aggregating by client IP to spot patterns A single 524 can be a fluke; a pattern of 524s concentrated on one IP + one path is a smoking gun. Run an aggregation like: ```bash # Caddy JSON example: count failures by IP and body size for an endpoint python3 -c " import sys, json from collections import Counter, defaultdict stats = defaultdict(lambda: {'total': 0, 'fail': 0, 'slow': 0, 'max_cl': 0}) for line in sys.stdin: d = json.loads(line) req = d.get('request', {}) if req.get('uri', '').startswith('/'): ip = req.get('headers', {}).get('Cf-Connecting-Ip', [''])[0] cl = int(req.get('headers', {}).get('Content-Length', ['0'])[0] or 0) dur = d.get('duration', 0) status = d.get('status', 0) s = stats[ip] s['total'] += 1 s['max_cl'] = max(s['max_cl'], cl) if status == 0: s['fail'] += 1 elif status == 200 and dur > 60: s['slow'] += 1 for ip, s in sorted(stats.items(), key=lambda x: -x[1]['fail']): print(f\"{ip}: total={s['total']} fail={s['fail']} slow={s['slow']} max_cl={s['max_cl']}\") " 125-second upstream silence in this incident. ### Step 5: Execute and record Run the experiment once, fully documented: command, environment, inputs, observed outputs, wall-clock timestamps. Compare against the prediction made in Step 2. If actual matches predicted, the hypothesis is calibrated. If not, the hypothesis is wrong — **do not rescue it with ad-hoc auxiliary hypotheses** ("oh, but maybe X also interferes..."). Return to Step 2 and write new hypotheses from scratch. ### Step 6: Counter-review Before committing to a root cause or shipping a fix, spawn independent reviewers to challenge the conclusion. Give them the same evidence, ask them to falsify, not confirm. Apply the four-question filter to each finding they raise: 1. **Probability** — will this actually happen? 2. **Cost** — what is the cost of fixing versus ignoring? 3. **Realistic scenario** — does this apply to the user's actual business case? 4. **Verification** — can I cheaply confirm or refute this? Classify every finding: real issue / partly right / unlikely / actively harmful. Never paste raw agent output to the user; filter first. See [references/counter-review-pattern.md](references/counter-review-pattern.md). ### Step 7: Fix and verify Apply the fix. Rerun the same decisive experiment from Step 3. Confirm the symptom no longer reproduces with the same setup that was reliably producing it. If the pre-fix state can no longer be reproduced after the fix, the fix cannot be proven — figure out why the repro was lost before declaring victory. ### Step 8: Document wrong turns The wrong turns in the investigation are more valuable than the right answer. Write an incident report capturing: - Symptom + direct evidence - Each hypothesis tried + how it was falsified - Decisive experiment design + result - Fix + verification - New monitoring or instrumentation added Future investigators — including future self — will read this to avoid the same cognitive traps. ## Common cognitive traps 1. **Circumstantial evidence convergence.** Five indirect clues all pointing the same direction feel like proof. They are not. If a direct probe is cheap, run it. 2. **Field-semantic confusion.** `duration=5.95s` can mean total wall time (one tool), handler execution phase (another tool), or TTFB (a third). Never cite a numeric field without verifying its semantics against documen … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [daymade](https://github.com/daymade) - **Source:** [daymade/claude-code-skills](https://github.com/daymade/claude-code-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-daymade-claude-code-skills-debugging-network-issues - Seller: https://agentstack.voostack.com/s/daymade - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.