Network Troubleshooting

Network Troubleshooting

This skill provides a concise, safety-first decision guide for diagnosing developer network failures. Diagnostics must stay read-only and target-scoped — this is not an automated remediation toolkit.

Safety Boundaries

These boundaries apply to every step of the workflow below and must never be relaxed, even if asked:

• Prefer read-only diagnostics and trusted project-provided diagnostic scripts.
• Use the failing host, URL, registry, or service as the default probe target — do not probe unrelated hosts.
• Ask before probing unrelated external services.
• Never 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.
• Never dump local configuration from npm, pnpm, yarn, pip, Git, Docker, shell, OS proxy, VPN, or certificate stores.
• Never disable, bypass, or skip TLS or certificate verification (no -k/--insecure, no NODE_TLS_REJECT_UNAUTHORIZED=0, no verify=False), even temporarily "just to test."
• Never change OS networking, DNS, proxy, package manager, Git, Docker, shell, VPN, or trust-store settings without explicit user approval for the exact action being taken.

Workflow

1. Collect — Capture the exact error text, the failing command, the target host/URL/port, OS/shell, proxy/VPN context, and whether the failure affects one target or many.
2. Classify — Match the symptom against the error classification table below to form a hypothesis.
3. Diagnose — Run only read-only checks scoped to the failing target, starting with the smallest relevant check.
4. Explain — Interpret each diagnostic result in plain language before suggesting any fix.
5. Advise — Present remediation options as choices; wait for explicit user approval before changing any state.
6. Verify — After an approved change, re-run the original failing command or an equivalent target-scoped check.

Error Classification

Safe Target-Scoped Checks

Choose the smallest relevant check and explain what it does before running it. Always substitute the specific failing <target-host>, <port>, and <path> — never a broader or unrelated target.

Connectivity

Linux/macOS:

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>

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 — check the certificate and HTTP status separately so a non-2xx response is never mislabeled as a certificate failure:

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

• Avoid raw config reads for proxy, package manager, Git, Docker, or OS network configuration.
• 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 exact probe target.

User-Approved Remediation Options

Present these as choices for the user to approve — never apply them automatically.

Verification

• After any user-approved change, re-run the original failing command whenever possible.
• If a smaller check is needed instead, keep it scoped to the same failing host, URL, registry, or service.
• Always explain what each diagnostic result means before recommending the next step.