If you work with Claude Code every day, you have probably seen your terminal freeze mid-task and print something like Connection dropped (ECONNRESET) or Unable to connect to API (ECONNRESET). The Claude Code ECONNRESET error is one of the most common network-related interruptions developers run into, and it can strike whether you're on a home Wi-Fi network, a corporate VPN, or a cloud dev environment.Claude Code ETIMEDOUT Error: Complete Troubleshooting Guide
This guide explains exactly what a claude code ECONNRESET error means, who is affected, why it happens, and most importantly how to fix it. You'll get a complete list of causes, the symptoms to look for, step-by-step solutions with real commands, advanced diagnostics, and prevention tips so it doesn't keep coming back.
Who is affected? Anyone running Claude Code, the CLI, the VS Code extension, the JetBrains plugin, the Desktop app, or Claude Code on the web can hit this error. It's especially common for developers behind corporate firewalls, VPN users, people on unstable home broadband, and anyone whose network path to Anthropic's API changes mid-session (for example, switching from Wi-Fi to a mobile hotspot). It isn't limited to Claude Code either: any tool that calls the Claude API directly over a long-lived or streaming HTTPS connection can hit the same error, including custom scripts and no-code automation platforms like n8n making requests straight to api.anthropic.com.
Why does it happen? ECONNRESET means the underlying TCP connection between the client and Anthropic's API was forcibly closed before the request finished. Something between your machine and api.anthropic.com , a router, proxy, firewall, VPN tunnel, a CDN edge node, or even your own operating system tore down the socket. It's rarely a sign that Anthropic's servers are down; in most cases, the cause sits on your side of the connection or somewhere on the network path between you and it.
By the end of this article, you'll know how to diagnose your specific case, apply the right fix, and set up your environment so claude code connection reset errors become rare instead of routine.
What Causes This Problem?
ECONNRESET is a transport-layer failure, so the causes span your network, your machine, and occasionally the request itself. Here are the most common ones, roughly in order of how often they show up in real-world reports.
1. VPN or proxy TLS inspection
Many corporate VPNs and security proxies perform TLS inspection; they intercept your HTTPS traffic, decrypt it, inspect it, and re-encrypt it before forwarding it on. Claude Code's HTTPS connections to api.anthropic.com don't always tolerate this cleanly, and the inspecting device can reset the socket instead of completing the handshake. This isn't just corporate VPNs, either consumer VPN clients cause the same failure. In one documented case, a developer calling the Claude API directly through an automation tool traced repeated ECONNRESET / "socket hang up" errors to a NordVPN connection; disconnecting the VPN resolved it immediately.
2. Network changes mid-session
Switching from office Wi-Fi to home Wi-Fi, or waking your laptop after it slept, can leave Claude Code holding a stale, pooled HTTP/2 connection. The old socket is already dead on the server side, but the client keeps trying to reuse it until it fails with ECONNRESET.
3. Firewall or antivirus interference
Corporate firewalls, endpoint security software, and some antivirus products actively terminate long-lived or streaming HTTPS connections they don't recognize, which is exactly the kind of connection Claude Code uses for streaming responses.
4. DNS and routing issues
An unstable or misconfigured DNS resolver, a flaky VPN tunnel, or a bad routing path can cause intermittent drops that surface as connection resets rather than clean timeouts.
5. Router or ISP buffer/MTU problems
On some home connections particularly asymmetric DSL or cable lines behind a consumer router a large network buffer can overflow during a long, data-heavy Claude Code session, causing the connection to reset partway through. This tends to correlate with session length rather than a specific action.
6. Authentication and token issues
An expired, corrupted, or incorrectly configured auth token can, in some configurations, cause the API server to reject the connection at the transport layer instead of returning a clean 401 Unauthorized, which surfaces as ECONNRESET rather than an authentication error.
7. Stale or buggy Claude Code builds
Older CLI versions had weaker retry logic and connection-pooling behavior. Anthropic has shipped multiple fixes to how Claude Code detects and recovers from dropped connections, so an outdated build can make resets both more frequent and harder to recover from. According to Anthropic's own error reference documentation, this has been an active area of change: how mid-stream drops, sleep/wake detection, and stalled-stream recovery are handled has been revised across many point releases (the docs cite specific behavior changes as recently as versions v2.1.199 through v2.1.234), so staying current genuinely matters here, not just as generic advice.
8. Streaming idle timeouts and CDN/edge behavior
Some networks, intermediate proxies, and even Anthropic's own edge infrastructure can drop connections that appear "idle" even if Claude is actively thinking and hasn't sent bytes recently. Anthropic's error reference confirms this is a real, named failure mode: The response stopped arriving when "the connection stayed open but stopped delivering data, so the streaming idle watchdog aborted it."
A widely-reported GitHub issue against Claude Code also pointed to a more specific variant of this: users seeing dozens of ECONNRESET errors per day during active sessions, with curl to the same endpoint succeeding every time, traced the pattern to connections being reset during pauses in streaming while the model was "thinking" or writing long files consistent with an edge/CDN node closing idle streaming connections before Claude Code finished reading the response, rather than any fault in the user's local network.
9. Incorrect proxy or environment variable configuration
Misconfigured HTTPS_PROXY, HTTP_PROXY, or ANTHROPIC_BASE_URL values can route traffic through a broken intermediary, causing resets that look network-related but are actually configuration errors.
Symptoms
Here's what a claude code ECONNRESET error typically looks like in the wild:
Terminal output showing API Error: Unable to connect to API (ECONNRESET) or Connection dropped (ECONNRESET)
Raw error detail in logs reading something like code=ECONNRESET, message=The socket connection was closed unexpectedly, sometimes alongside failed telemetry/event export lines (OTEL diag error: Failed to export events (code=ECONNRESET)) these telemetry failures are a side effect, not the root cause
A retry countdown such as Retrying in 7 seconds… (attempt 5/10) that eventually exhausts all attempts
The banner Waiting for API response · will retry in … · check your network, which Claude Code shows when no data has arrived on the response stream for 20 seconds (90 seconds during advisor review) this appears before a retry has even started, so it isn't itself a failure yet
The session appearing to "freeze" with no thinking tokens or output after a reset
The error recurring roughly every 5–15 minutes during long coding sessions, or in more severe cases dozens of times per day during active use
Errors appearing immediately on every prompt, including simple ones like hi
The problem disappearing on a mobile hotspot but returning on office or home Wi-Fi, or disappearing the moment a VPN client is disconnected
curl -v https://api.anthropic.com completing a clean TLS handshake even while Claude Code fails a strong sign the issue is client-side or specific to long-lived streaming connections, not a server outage
Errors that started suddenly after a network switch, VPN connection, or OS sleep/wake cycle
In non-CLI integrations (custom scripts, n8n, other automation tools calling the Messages API directly), the same failure surfaces as ECONNRESET or "socket hang up" on the HTTP request node/library itself
If you see the TLS handshake succeed with curl but Claude Code still fails, that's your biggest clue: the network path itself is fine, and the problem is in how Claude Code (or something sitting between it and the API) manages that specific long-lived connection.
Step-by-Step Solutions
Work through these in order. Most people find their fix in the first three or four steps.
Fix 1: Confirm it's not an Anthropic outage
Why it works: Ruling out a server-side incident first saves you from chasing a local fix for a global problem.
bash
# Check Anthropic's status page in your browser
open https://status.claude.com
Expected result: No active incidents. If status.claude.com shows a problem, wait it out — no local fix will help.
Fix 2: Run Claude Code's built-in diagnostics
Why it works: /doctor checks your local environment, authentication, and connectivity in one pass and tells you what's misconfigured. /status shows which credential and connection method is actually active, which matters because a stray ANTHROPIC_API_KEY or an ANTHROPIC_BASE_URL pointed at a gateway can be the real source of connection trouble even when it looks like a pure network issue.
bash
claude
# then inside the session:
/doctor
/status
Expected result: A report flagging any broken auth, proxy, or connectivity settings, plus confirmation of which credential and API endpoint your session is actually using. Fix whatever it identifies before moving on.
Fix 3: Disable VPN or proxy temporarily
Why it works: VPNs and security proxies that perform TLS inspection are the single most common cause of ECONNRESET with Claude Code. This isn't limited to corporate VPN clients; consumer VPNs (NordVPN, for example, has been directly implicated in reported cases) cause the identical failure. Removing the VPN or proxy from the path confirms or rules out the tunnel as the culprit.
bash
Expected result: A report flagging any broken auth, proxy, or connectivity settings, plus confirmation of which credential and API endpoint your session is actually using. Fix whatever it identifies before moving on. Fix 3: Disable VPN or proxy temporarily Why it works: VPNs and security proxies that perform TLS inspection are the single most common cause of ECONNRESET with Claude Code. This isn't limited to corporate VPN clients; consumer VPNs (NordVPN, for example, has been directly implicated in reported cases) cause the identical failure. Removing the VPN or proxy from the path confirms or rules out the tunnel as the culprit.
Expected result: If the error disappears, your VPN or proxy is the cause. Work with your network/security team to allowlist api.anthropic.com, or add a TLS inspection bypass rule for that host. If it's a personal VPN, keep it disconnected while using Claude Code, or check whether your VPN client has a split-tunneling option you can apply to api.anthropic.com.
Fix 4: Test raw connectivity with curl
Why it works: A verbose curl request isolates whether the problem is your network path (DNS, TLS, routing) or something specific to Claude Code's long-lived, streaming HTTP client. Note that a successful curl does not fully rule out the issue — curl requests are quick and don't hold the connection open the way a streaming Claude Code response does, so intermittent idle-timeout resets on streaming connections can still occur even when every curl test passes.
bash
curl -v https://api.anthropic.com
Expected result: A 404 or 405 response is actually good news — it means DNS, TCP, and TLS all completed successfully, and the failure is happening inside Claude Code's connection handling, a proxy in the path, or an edge node's idle-timeout behavior, rather than your basic network reachability.
curl result | What it means |
|---|---|
404, 405, or an auth error | Server reachable, TLS working — problem is local to Claude Code, proxy, streaming idle timeouts, or app-layer config |
TLS handshake failure | VPN/proxy TLS inspection or a missing certificate bundle |
Connection timeout / refused | Firewall, DNS, or routing problem |
Fix 5: Update Claude Code to the latest version
Why it works: Anthropic has repeatedly improved retry logic, connection pooling, and reset handling across recent releases; this is documented, not just anecdotal. Anthropic's error reference lists multiple version-specific fixes to how dropped connections, mid-response failures, and stalled streams are retried and reported, so an outdated build is measurably more likely to hang or fail ungracefully instead of recovering.
bash
# Check your current version
claude --version
# Update (method depends on how you installed it)
npm install -g @anthropic-ai/claude-code@latest
Expected result: After updating, fully quit and relaunch your terminal (not just the clause process) so any stale connection state clears.
Fix 6: Restart the process instead of retrying in place
Why it works: In several documented cases, once Claude Code's connection pool gets into a bad state after a network change, it doesn't recover on its own even after connectivity is confirmed healthy. A full process restart forces new sockets.
bash
pkill -f claude
claude
Expected result: A fresh session with a new connection pool, clearing any stale HTTP/2 socket reuse issues left over from a network switch or sleep/wake cycle.
Fix 7: Re-authenticate
Why it works: If an expired or corrupted token is causing the server to reject the connection at the transport layer, refreshing your credentials resolves it cleanly.
bash
claude
# inside the session:
/login
Expected result: A successful re-authentication, followed by normal API responses on your next prompt.
Fix 8: Check for antivirus or endpoint security interference
Why it works: Some endpoint security tools terminate long-lived or streaming connections by default. Temporarily disabling them (or adding an exception) confirms whether they're responsible.
What to do: Add api.anthropic.com to your antivirus/EDR allowlist, or temporarily disable HTTPS scanning and retest.
Expected result: If the error stops, work with IT to create a permanent exception rather than leaving protection disabled.
Advanced Fixes
If the basic fixes above didn't resolve it, these are for persistent or environment-specific cases.
Understand what Claude Code actually retries automatically
Before tuning anything, it helps to know what's already happening under the hood, per Anthropic's own documentation:
Claude Code retries transient failures up to 10 times by default with exponential backoff before showing you an error.
A connection that drops before any part of Claude's response (including its thinking) has streamed gets re-issued with the same backoff, and the turn continues normally.
A connection that drops after Claude has finished thinking but before any text or tool call has started gets re-issued up to two times in quick succession; if it keeps failing at that exact point, you'll see Connection lost before a response was produced.
A connection that drops after Claude has already produced a block of text or a tool call is not retried — Claude Code keeps what was already completed and shows The response above may be incomplete instead, because retrying could re-run the same tool call twice.
TLS certificate validation failures are never retried, even once. This matters diagnostically: if your error appears instantly and identically on every single attempt with zero retry countdown, it's very likely a certificate problem (see Fix below), not a flaky network — a flaky network almost always shows at least a few retry attempts before failing.
Knowing this split helps you read the failure pattern correctly instead of guessing.
Tune retry behavior with environment variables
You can tune how aggressively Claude Code retries:
bash
# Increase retry attempts for unstable networks or CI jobs
export CLAUDE_CODE_MAX_RETRIES=15
# Retry rate-limit, capacity, and other transient errors far more persistently
# (useful in CI/unattended sessions) — raises the effective retry count to
# roughly 300 attempts (~3 hours of backoff) and removes the normal cap
export CLAUDE_CODE_RETRY_WATCHDOG=1
# Raise the per-request timeout for slow networks or proxies (milliseconds)
export API_TIMEOUT_MS=900000
Variable | Default | What it does |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES | 10 | Number of retry attempts before Claude Code gives up and surfaces the error. Normally capped at 15. |
CLAUDE_CODE_RETRY_WATCHDOG | unset | Set to 1 for unattended/CI sessions to retry 429/529 capacity errors indefinitely, and raises the retry count for other transient failures (server errors, timeouts, dropped connections) to around 300 attempts, removing the usual 15-attempt cap. |
API_TIMEOUT_MS | 600000 (10 min) | Per-request timeout; raise it if you're on a slow or high-latency network. |
Check proxy environment variables
Misconfigured proxy variables are a frequent, easy-to-miss cause:
bash
env | grep -i proxy
env | grep ANTHROPIC
Make sure HTTPS_PROXY, HTTP_PROXY, and any custom ANTHROPIC_BASE_URL actually point where you think they do. A stray or outdated value picked up from a shell profile, .env file, or IDE terminal is a common culprit. Note also that pointing ANTHROPIC_BASE_URL at anything other than api.anthropic.com an LLM gateway, proxy, or third-party routing layer changes how Claude Code reports and retries some failures (for example, Bedrock-style streaming responses aren't retried the same way as a direct connection), so ruling this variable in or out early saves time.
Fix TLS certificate issues behind corporate proxies
If your organization uses a TLS-inspecting proxy with a custom root certificate, Claude Code needs to trust that certificate explicitly; this failure type is not automatically retried, so it will fail immediately and consistently rather than intermittently.
bash
export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-root-ca.pem
Expected result: TLS handshakes succeed instead of failing on certificate validation, and connections stop resetting during the handshake step.
Analyze debug logs
Run Claude Code in debug mode to see exactly where a connection is failing:
claude --debug
Look for the point where the connection drops during the TLS handshake, mid-stream, or while idle. This tells you whether to focus on certificates, proxy configuration, or idle-timeout behavior. If you see the drop consistently landing during a pause in streaming output (the model "thinking" or writing a long file) rather than at connection start, that pattern points toward an idle-timeout being enforced somewhere on the path by your proxy, a corporate firewall, or an edge/CDN node rather than a fundamental reachability problem.
Test with a minimal, non-streaming request
Streaming connections are more sensitive to idle-timeout drops than simple requests. Isolate the issue:
curl -v --max-time 30 https://api.anthropic.com
If a short request always succeeds but long Claude Code sessions fail, the cause is more likely an idle/streaming timeout somewhere on your network path (or, per documented user reports, on the API's edge infrastructure itself) rather than a fundamental connectivity problem.
Check for buffer/MTU issues on home networks
If sessions consistently die after a similar amount of data has been transferred (rather than a fixed amount of time), a consumer router's oversized send buffer can be the cause. Capping your machine's TCP send buffer or testing on a different network (like a mobile hotspot) can confirm this.
If you're calling the API directly (not through Claude Code)
If you're hitting ECONNRESET or "socket hang up" from a custom script, backend service, or a no-code tool like n8n calling api.anthropic.com directly, the same root causes apply VPNs and TLS-inspecting proxies are the most commonly confirmed culprit in real-world reports. Test with a VPN fully disconnected before assuming it's a bug in your integration, and make sure your HTTP client's timeout is generous enough for a full streaming response rather than a single request/response cycle.
Prevention Tips
Keep Claude Code updated. Run claude --version regularly and update connection-handling improvements ship frequently and are documented release over release.
Allowlist api.anthropic.com in your VPN, proxy, and antivirus/EDR configuration instead of routing it through TLS inspection.
Avoid switching networks mid-session when possible; if you must, restart Claude Code afterward rather than waiting for it to self-recover.
Set CLAUDE_CODE_RETRY_WATCHDOG=1 in CI/CD or unattended environments so transient network blips don't kill automated jobs.
Monitor /status inside a Claude Code session to confirm your active credentials and connection method before long work sessions.
Use a wired connection or a known-stable network for long-running, context-heavy sessions if you're prone to resets on Wi-Fi.
Check status.claude.com as your first step whenever something feels off, so you don't waste time debugging a server-side incident.
If you use a personal VPN, test with it off first. Consumer VPN clients have been directly confirmed as a cause of ECONNRESET/"socket hang up" errors against the Claude API, not just corporate ones.
FAQ Section
It means the TCP connection between Claude Code and the Anthropic API was closed unexpectedly, before the request could complete — typically by a network device such as a router, VPN, firewall, or proxy, or by an idle-connection timeout somewhere on the path, rather than by Claude Code itself.
No. In the large majority of cases, it's caused by something on the user's side of the connection — a VPN, proxy, unstable Wi-Fi, or firewall — or by an idle-timeout on a long-lived streaming connection, rather than by Claude Code's code or Anthropic's servers. That said, documented reports (including a widely-discussed GitHub issue) point to cases where an edge/CDN node appears to close idle streaming connections mid-response even when the user's own network is verified clean end to end, so it isn't exclusively a client-side problem in every case.
curl completing a TLS handshake proves DNS, routing, and TLS are healthy. Claude Code can still fail if the issue is specific to long-lived or streaming connections, stale connection pooling, or an intermediary (or edge node) that treats streaming traffic differently from a quick request-response cycle.
Yes. Switching Wi-Fi networks or waking your laptop from sleep can leave Claude Code holding a dead, pooled connection that it keeps trying to reuse until it fails. Restarting the process usually resolves this.
By default, Claude Code retries transient failures automatically with exponential backoff, up to 10 attempts, before showing you the error. You can raise this with CLAUDE_CODE_MAX_RETRIES (capped at 15) or CLAUDE_CODE_RETRY_WATCHDOG=1 (roughly 300 attempts for CI/unattended use). Note that TLS certificate failures are never retried — they fail immediately on the first attempt — and a failure that lands after Claude has already produced text or a tool call is also not retried, to avoid duplicate tool execution.
Yes. Some endpoint security and antivirus tools actively terminate long-lived or streaming HTTPS connections, which can surface as ECONNRESET in Claude Code.
It's not just corporate networks. Consumer VPN clients have been directly implicated in confirmed reports of ECONNRESET / "socket hang up" errors against the Claude API — one documented case traced the exact failure to a NordVPN connection and resolved it by disconnecting the VPN. Test with any personal VPN off before ruling it out.
Sometimes, if the issue is caused by a corrupted local install or an outdated binary with weaker connection handling. It won't help if the root cause is your network, proxy, VPN, or an idle-timeout on the API's edge infrastructure — check those first.
Conclusion
The claude code econnreset error comes down to one thing: your TCP connection to Anthropic's API got cut off before the request finished. The root cause is almost always local a VPN or proxy doing TLS inspection, a network switch that left a stale connection in the pool, a firewall or antivirus tool terminating streaming traffic, or a misconfigured proxy environment variable though documented reports also point to idle-timeout behavior on long-lived streaming connections, sometimes on the network path and sometimes on the API's own edge infrastructure, as a distinct and less obvious cause.
The best starting solution for most people is simple: disable your VPN or proxy temporarily and retest, run /doctor and /status inside Claude Code, and confirm with a verbose curl request whether the network path itself is healthy keeping in mind that a passing curl test doesn't fully rule out a streaming-specific idle timeout. If those don't resolve it, move on to updating Claude Code, restarting the process fully, re-authenticating, and for persistent corporate environments trusting your proxy's TLS certificate with NODE_EXTRA_CA_CERTS.
To prevent it from coming back, keep Claude Code updated, allowlist api.anthropic.com in your security tools, avoid switching networks mid-session, and tune the retry environment variables for automated or CI workflows. With those in place, fixing claude code econnreset issues become a rare, quick diagnosis rather than a recurring headache.