Network Troubleshoot

Führt systematisch durch Netzwerk-Diagnose bei DNS-, Port- oder Firewall-Problemen.

Original-Beschreibung der Autoren: Systematic, safety-first network troubleshooting for developers

Die Regel

---
description: Systematic, safety-first network troubleshooting for developers
globs: **/*
alwaysApply: false
---

# Network Troubleshoot

Use this rule as a concise decision guide for developer network failures. Keep diagnostics safe, target-scoped, and read-only. Do not turn this rule into an automated remediation toolkit.

## Safety Boundaries

- Prefer read-only diagnostics and trusted project-provided diagnostic scripts.
- Use the failing host, URL, registry, or service as the default probe target.
- Ask before probing unrelated external services.
- Do not print proxy URLs, credentials, tokens, auth headers, package index URLs, registry hostnames from config, or raw config values in shared output.
- Internal hosts and URLs may be collected for target-scoped local diagnostics, but replace them with placeholders before sharing logs or reports unless the user explicitly approves including them.
- Do not dump local config from npm, pnpm, yarn, pip, Git, Docker, shell, OS proxy, VPN, or certificate stores.
- Do not disable, bypass, or skip TLS or certificate verification.
- 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.

## Workflow

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 and wait for user approval before changing state.
6. **Verify**: Re-run the original failing command or an equivalent target-scoped check.

## Error Classification

| Error Pattern | Likely Category |
|---|---|
| `ECONNREFUSED`, `ERR_CONNECTION_REFUSED`, `Connection refused` | Target service or port is not listening |
| `ECONNRESET`, `socket hang up`, `Connection reset` | Connection dropped by target, proxy, firewall, or middlebox |
| `ETIMEDOUT`, `ERR_CONNECTION_TIMED_OUT`, `timed out` | Routing, firewall, proxy, or target availability |
| `ENOTFOUND`, `EAI_NONAME`, `ERR_NAME_NOT_RESOLVED`, `getaddrinfo` | DNS or hostname issue |
| `ERR_PROXY_CONNECTION_FAILED`, proxy tunnel errors, HTTP `407` | Proxy configuration or proxy authentication |
| `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, `CERT_HAS_EXPIRED`, `self signed`, `ERR_CERT_*` | TLS certificate or local trust issue |
| HTTP `403` | Authorization, IP allowlist, CORS, or policy block |
| HTTP `502`, `503`, `504` | Upstream service, gateway, CDN, or transient server issue |
| `npm ERR! network`, package install timeout, `pip` timeout | Package registry, proxy, DNS, or network path issue |
| `fatal: unable to access`, Git fetch/push timeout | Git remote, proxy, DNS, TLS, or network path issue |

## Safe Target-Scoped Checks

Choose the smallest relevant set. Explain what each command checks before running it.

### Connectivity

Linux/macOS:

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

Windows PowerShell:

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

DNS

Linux/macOS:

nslookup <target-host>
dig <target-host>                # Linux/macOS, if available

Windows PowerShell:

Resolve-DnsName <target-host>

HTTP

Linux/macOS:

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>
curl -I https://<target-host>/<path>

Windows PowerShell:

$uri = "https://<target-host>/<path>"
try {
  $resp = Invoke-WebRequest -Uri $uri -Method Head -TimeoutSec 10
  "HTTP status: $([int]$resp.StatusCode)"
} catch [Net.WebException] {
  if ($_.Exception.Response) {
    "HTTP status: $([int]$_.Exception.Response.StatusCode)"
  } else {
    "HTTP request failed: $($_.Exception.Message)"
  }
}

TLS

Linux/macOS:

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

Windows PowerShell:

Use HEAD and report HTTP statuses separately from TLS or network errors so non-2xx responses are not mislabeled as certificate failures.

try {
  $req = [Net.HttpWebRequest]::Create("https://<target-host>:<port>/<path>")
  $req.Method = "HEAD"
  $req.Timeout = 5000

  try {
    $resp = $req.GetResponse()
  } catch [Net.WebException] {
    $resp = $_.Exception.Response
    if ($req.ServicePoint.Certificate) {
      $cert = $req.ServicePoint.Certificate
      "Cert subject: $($cert.Subject)"
      "Cert expires: $($cert.GetExpirationDateString())"
    }
    if ($resp) {
      "HTTP status: $([int]$resp.StatusCode) $($resp.StatusDescription)"
      $resp.Close()
    } else {
      "TLS/network error: $($_.Exception.Message)"
    }
    return
  }

  $cert = $req.ServicePoint.Certificate
  if ($cert) {
    "Cert subject: $($cert.Subject)"
    "Cert expires: $($cert.GetExpirationDateString())"
  }
  "HTTP status: $([int]$resp.StatusCode) $($resp.StatusDescription)"
  $resp.Close()
} catch {
  "TLS/network error: $($_.Exception.Message)"
}

Proxy And Package Managers

For proxy, package manager, Git, Docker, and OS network configuration, avoid raw config reads. Report only whether relevant settings appear present when this can be checked without printing values. If the available command would print a URL, token, internal hostname, auth header, or full config value, do not run it.

Only perform package registry probes when the failed operation already targeted that registry, or after the user approves that … (hier gekürzt — Kopieren/Download liefert die vollständige Regel)

## So nutzt du sie

Die Regel kopieren (Button oben) oder als Datei herunterladen und im Projekt unter `.cursor/rules/` ablegen — Cursor lädt sie beim nächsten Start automatisch. Ältere Cursor-Versionen lesen alternativ eine einzelne `.cursorrules`-Datei im Projektstamm; dort einfach den Regel-Text ohne den Kopfblock zwischen den `---`-Zeilen einfügen.

Der Regel-Text ist englisch — Cursor versteht ihn unabhängig von der Sprache, in der Sie mit dem Editor chatten.


## Im Detail

Eine Regel für systematisches Netzwerk-Debugging – sie strukturiert die Fehlersuche bei DNS-Problemen, blockierten Ports, Firewall-Regeln oder Latenz-Auffälligkeiten, statt wahllos Befehle vorzuschlagen. Der Mehrwert liegt in der Reihenfolge: Sie leitet dazu an, erst grundlegende Ebenen zu prüfen (Erreichbarkeit, DNS-Auflösung), bevor komplexere Ursachen wie Routing oder Anwendungs-Timeouts untersucht werden. Das ist besonders bei Server- oder Infrastruktur-Arbeit hilfreich, wo unsystematisches Debugging schnell Zeit kostet. Kein Ersatz für tiefes Netzwerkwissen, aber gut als Checkliste, wenn man selten mit Netzwerk-Diagnose zu tun hat und keine falsche Ursache vorschnell ausschließen möchte.

## Praxis-Tipp

Bei "Server X ist von Rechner Y nicht erreichbar" führt die Regel schrittweise durch ping, DNS-Check, Portscan und Firewall-Regeln statt direkt eine Lösung zu raten.

## Lizenz & Quelle

- **Lizenz:** CC0 1.0
- **Quelle:** [PatrickJS/awesome-cursorrules (GitHub)](https://github.com/PatrickJS/awesome-cursorrules)

Lade …