Direct answer
A reset means a TCP connection was closed unexpectedly. The phase and connection-reuse pattern usually distinguish stale pools from proxy or upstream termination.
What this guide helps you solve
Resolve ECONNRESET, socket hang up, and connection reset errors without duplicating side effects.
Symptoms
The client reports ECONNRESET, socket hang up, or connection reset by peer during request or response transfer.
Failures may cluster on reused idle connections, long streams, large uploads, or proxy timeout boundaries.
Likely causes
- A stale keep-alive connection is reused after the server or proxy idle timeout.
- A proxy, firewall, load balancer, or upstream actively closes the connection.
- The client cancels or aborts while another layer still reads or writes.
- Connection-pool limits or lifecycle settings conflict across hops.
Diagnostic procedure
- 01Establish the boundaryMark whether the reset occurred while writing, waiting for first byte, or reading the response.
- 02Create a baselineEstablish a baseline with model discovery and one short non-streaming request.
- 03Compare one variableCompare a forced new connection with normal keep-alive reuse.
- 04Record decisive evidenceCorrelate proxy logs with UTC time, connection metadata, and request ID.
curl -sS --http1.1 -H 'Connection: close' --connect-timeout 10 --max-time 60 -o /tmp/reset-body.json -w 'remote=%{remote_ip} status=%{http_code} total=%{time_total}
' 'https://<your-api-host>/v1/models' -H "Authorization: Bearer ${API_KEY:?set API_KEY first}"
Remediation
- 01Correct the failing layerSet client idle lifetime below the shortest server or proxy idle timeout.
- 02Restore required behaviorCalibrate pool size, queue wait, keep-alive, and read deadlines across hops.
- 03Remove temporary workaroundsRetry only replay-safe operations with bounded backoff and cancellation cleanup.
Verification
- Pool size, idle lifetime, and queue timeout remain stable under load.
- The client retires connections before an upstream idle deadline.
- Only safe requests retry, with capped attempts and total time.
- No tool call or external write is duplicated after a reset.
Sensitive diagnostic data
- Do not disable TLS or proxy controls to test a reset.
- Treat an ambiguous write as potentially completed before retrying.
- Redact network traces that contain headers or payloads.
- Escalate with phase, reuse state, UTC time, proxy layer, and request ID.
Official sources and verification scope
This guide is grounded in protocol specifications and official client documentation. Error text, retry headers, and configuration fields may change by service or client version; verify the sources and redact logs and request samples before sharing.
View documentation scope