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.
Confirm the symptom and blast radius
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.
- Capture the status or exception, response body, request ID, UTC time, client version, and final host before changing configuration.
- Compare one minimal request with the failing workflow to determine whether the issue is global, model-specific, or feature-specific.
- Keep credentials, full prompts, customer data, and private file contents out of screenshots and support bundles.
Common causes and ownership boundaries
Treat the error as evidence from one layer, not as proof that every downstream component failed. These are the highest-value causes to test first.
- 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.
Run a layered minimal diagnosis
Start with a request that has the fewest moving parts. Preserve the same account, API host, and target model while removing optional features.
Change one variable at a time and retain the raw status, headers, response body, and timing. This separates client serialization from gateway and upstream behavior.
- 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}"
Apply the fix at the confirmed root cause
Make the smallest change that addresses the proven layer. Avoid hiding deterministic configuration failures behind broad retries or disabled validation.
- 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.
Verify the repair, not just one successful call
Repeat the original path after the minimal check succeeds, then verify stable behavior under normal streaming, concurrency, and timeout conditions.
- 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.
Security boundaries and escalation evidence
Collect enough evidence to reproduce and escalate the failure without exposing credentials or weakening transport, permission, and validation controls.
- 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.
Read the verification methodology