Network Troubleshooting Cursor Rules

tl;dr: paste this .mdc into .cursor/rules/ to make Cursor treat network failures as read-only diagnostics — never auto-edit OS, DNS, proxy, package manager, Git, Docker, or trust-store config without your explicit approval.

What the upstream rule covers

Sourced verbatim from PatrickJS/awesome-cursorrules → network-troubleshoot.mdc. The rule is a decision guide, not an automation toolkit. It classifies common errors, gives safe per-platform commands (Linux/macOS and Windows PowerShell), and forces user approval before any remediation that touches system state.

What it tells Cursor

• Safety boundaries first. Read-only diagnostics only. Never print proxy URLs, credentials, tokens, auth headers, package index URLs, registry hostnames from config, or raw config values. Replace internal hosts with placeholders before sharing logs unless the user explicitly approves.
• No config dumps. Never dump local config from npm, pnpm, yarn, pip, Git, Docker, shell, OS proxy, VPN, or certificate stores.
• No TLS bypass. Do not disable, bypass, or skip TLS or certificate verification.
• No state changes without approval. Do not change OS networking, DNS, proxy, package manager, Git, Docker, shell, VPN, or trust-store settings without explicit user approval for the exact action.

The workflow the rule enforces

1. Collect. Capture the exact error, failing command, target host/URL/port, OS/shell, proxy/VPN context, and whether the failure affects one target or many.
2. Classify. Match the symptom to the most likely category.
3. Diagnose. Run only read-only checks scoped to the failing target.
4. Explain. Interpret the output before suggesting any fix.
5. Advise. Present remediation options as choices; wait for user approval before changing state.
6. Verify. Re-run the original failing command or an equivalent target-scoped check.

Error classification table the rule bakes in

Safe target-scoped checks (selection from the rule)

Connectivity (Linux/macOS):

ping -c 4 <target-host>
curl -v telnet://<target-host>:<port> --connect-timeout 5

Connectivity (Windows PowerShell):

Test-Connection -ComputerName <target-host> -Count 4
Test-NetConnection -ComputerName <target-host> -Port <port>

HTTP timing breakdown:

curl -vvv -o /dev/null \
  -w "HTTP %{http_code}\nTime: %{time_total}s\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\n" \
  https://<target-host>/<path>

TLS subject and expiry (no full chain dump):

echo | openssl s_client -connect <target-host>:<port> -servername <target-host> 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

Install

mkdir -p .cursor/rules
curl -L -o .cursor/rules/network-troubleshoot.mdc \
  https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/network-troubleshoot.mdc

Gotchas

• The rule is intentionally non-automating. Cursor will not “fix” your proxy or trust store on its own. If you wanted a rule that retries installs with --insecure or flips strict-ssl to false, this is the opposite of what you want — write a separate rule for that and accept the footgun.
• The rule’s diagnostics scripts include PowerShell snippets using [Net.HttpWebRequest] and [Net.WebException] — modern PS prefers Invoke-WebRequest with try/catch. The upstream keeps the older form because it surfaces ServicePoint.Certificate directly without the PS7 TLS changes.
• globs: **/* means Cursor attaches this on any file. If you also ship a framework rule with a narrower glob, the framework rule wins on matching files. This rule still triggers when Cursor is invoked with network-error context.
• The rule explicitly forbids dumping proxy URLs and config values — even when the user asks “just print the npm config”. Cursor will refuse. That’s the point.

Related

• Anti-Sycophancy Code Discipline Cursor Rules — pairs well when AI agents are the ones running network commands
• JavaScript / TypeScript Code Quality Cursor Rules — for the actual codebase Cursor is editing while it debugs network errors
• Tailwind CSS Cursor Rules — generic frontend rule that often co-exists on the same project
• Cursor Rules Guide