Fix for Claude Code (and any large HTTPS upload) failing with
API Error: Unable to connect to API (ECONNRESET)
on a specific home network.
- Short Claude requests always work; long sessions reset after ~5–13 min.
- Works fine on a phone hotspot, fails on home Wi-Fi.
- Debug log shows the same request retried 11 times, each dying at a
consistent
~15 s, then
code=ECONNRESET
.
It is not MTU, IPv6, a proxy, the client, or idle-connection reaping — all ruled out by testing. It is the upload direction.
Every Claude request uploads the full conversation context as the POST body.
- macOS auto-tunes the TCP send buffer up to
net.inet.tcp.autosndbufmax
(stock default4 MB). - A large body lets a single connection burst multiple MB into the DSL modem's upstream buffer all at once.
- That buffer tail-drops at ~2.29 MB on this line. The flow stalls and the
server resets it ~15 s later → Claude retries 11× →
ECONNRESET
.
Small requests never burst that far, so they succeed. The hotspot's path absorbs the burst differently, so it succeeds too. The uplink itself is fast (~24 Mbit measured) — the only problem is the unpaced burst.
Capping the send buffer to 256 KiB bounds in-flight data far below the 2.29 MB overflow point, so a single connection can never overflow the modem buffer. The link's bandwidth-delay product is only ~22 KB, so the cap costs zero throughput.
A 100 MB upload to https://speed.cloudflare.com/__up
reproduced it exactly:
reset at 2.29 MB / 15 s with the default 4 MB buffer; full 100 MB at 3 MB/s
with the 256 KiB cap. Throttled curl --limit-rate
uploads also always succeeded, proving pacing — not size or time — was the fix.
upload-fix on # apply cap + install LaunchDaemon (persists across reboot)
upload-fix off # remove LaunchDaemon + restore macOS defaults
upload-fix status # show current state (no sudo)
upload-fix on 131072 # tighter 128 KiB cap (if a heavily-parallel session resets)
on
/ off
self-elevate (one sudo prompt). status
is read-only.
| setting | stock macOS | this fix |
|---|---|---|
net.inet.tcp.autosndbufmax |
||
| 4194304 | 262144 | |
net.inet.tcp.sendspace |
||
| 131072 | 262144 |
This is a CPE/line trait — a modern line shouldn't tail-drop a burst like this. The device-independent fix is a router doing SQM / fq_codel (e.g. put the Speedport in bridge mode behind an OpenWrt router, or a Fritz!Box with shaping). Until then, this per-host cap keeps things working.