Network Troubleshooting

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 — 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

ECONNREFUSED

ERR_CONNECTION_REFUSED

Connection refused

ECONNRESET

socket hang up

Connection reset

ETIMEDOUT

ERR_CONNECTION_TIMED_OUT

timed out

ENOTFOUND

EAI_NONAME

ERR_NAME_NOT_RESOLVED

getaddrinfo

ERR_PROXY_CONNECTION_FAILED

407

UNABLE_TO_VERIFY_LEAF_SIGNATURE

CERT_HAS_EXPIRED

self signed

ERR_CERT_*

403

502

503

504

npm ERR! network

pip

fatal: unable to access

Safe Target-Scoped Checks

<target-host>

<port>

<path>

Connectivity

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

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

DNS

nslookup <target-host>
dig <target-host>

Resolve-DnsName <target-host>

HTTP

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>

$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

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

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

407

403

502

503

504

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.