## Question
How should ETIMEDOUT distinguish connection establishment from response-body delay?
## Why this matters
Recurring public developer task for HTTP and integration errors.
## Environment / product
HTTP and integration errors
## What needs to be determined
Current researched guidance, applicability, limitations, and primary sources for this question.
Researched guidance is proposed, not an execution report.
Problem details
- Observed symptom
- How should ETIMEDOUT distinguish connection establishment from response-body delay?
- Context
- Recurring public developer task; researched guidance is proposed, not an execution report.
- Environment
- Unknown · not established
- Symptom signature
- Literal source
- Not supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Researched guidance: How should ETIMEDOUT distinguish connection establishment from response-body delay?
## Summary
Classify ETIMEDOUT by the last completed request phase and by the timer that fired, not by the error code alone. Instrument DNS, connection, request-write, response-header/first-byte, and body-complete boundaries; then distinguish connection establishment failure from post-connect pre-header delay and from a response-body stall.
## Candidate action
Use monotonic timestamps and phase markers for every request. Record DNS start/end, each connection attempt start/end, TLS handshake completion when applicable, connection acquisition and whether it was reused, request-write completion, response headers/first byte, each body-read or data event, and body end. On timeout, record the timer name, last completed marker, and whether the connection was reused. Classify as establishment timeout when the relevant connection was never obtained (or the last phase is DNS, TCP, TLS, or QUIC setup); classify as post-connect pre-header/TTFB delay when a new or reused connection exists but response headers have not arrived; classify as response-body delay when response headers/first byte have arrived but body progress or end has not. Use phase-specific controls where the client provides them: curl’s connect timeout is for DNS and connection handshakes, while its maximum-time limit covers the whole operation including transfer. In Node, treat ClientRequest response as the header boundary, IncomingMessage data/end as body progress/completion, and remember that request/socket timeout reports inactivity and does not destroy the request automatically. In Go, attach httptrace.ClientTrace and use DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn (including Reused), WroteRequest, and GotFirstResponseByte, plus body-read timestamps; use the RoundTrip error for failures to obtain a connection. Preserve separate connect, response-idle, and overall deadlines so a total deadline firing during any phase is not mislabeled as a connection failure.
## Applicability
- HTTP clients and integrations that expose ETIMEDOUT or an equivalent timeout while establishing a connection, waiting for response headers, or reading a response body.
- Node.js HTTP/HTTPS clients, Go net/http clients, curl-based diagnostics, and similar clients where phase timing can be instrumented.
- Requests using pooled or reused connections, where a new TCP connection may not be created for the request.
## Key findings
- Node HTTP defines the response event as the point at which response headers have been received; the response body is delivered separately through IncomingMessage, and request timeout is a socket inactivity notification that does not itself abort the request. (S1)
- Node net distinguishes lookup before connecting, connection attempts and their timeouts, successful connect, and socket inactivity timeout; a connect problem emits error instead of connect. (S2)
- Node TLS documents secureConnect after the client handshake completes, while certificate authorization must still be checked separately. (S3)
- Go httptrace exposes DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn with reuse information, WroteRequest, and GotFirstResponseByte; it notes that hooks may be absent or repeated and that RoundTrip errors cover failure to obtain a connection. (S4)
- curl separates connection establishment timing from total operation timing: connect timeout covers DNS and TCP/TLS/QUIC handshakes, whereas maximum time applies regardless of whether data is still being transferred. (S5)
## Known limitations
- ETIMEDOUT is not a universal phase-specific diagnosis; libraries and operating systems may report different error names or collapse DNS, TCP, TLS, and idle-read failures.
- A response-header marker proves that the server has started the HTTP response, not that the body is available or complete; body progress still needs a read/data/end measurement.
- Connection reuse, HTTP/2 multiplexing, proxies, and QUIC can make connection-level timing distinct from per-request timing; correlate the request with the client’s connection or stream identifiers when available.
- Node socket/request timeouts are inactivity notifications and do not abort automatically; Go httptrace provides hooks but not timeout policy and its hooks may be nil, concurrent, or repeated for retries and address-family attempts.
- This is researched guidance only: no endpoint, client request, timeout, or independent reproduction was executed.
## Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
- The cited documentation defines phase boundaries and timeout semantics; it does not establish how a particular production client or operating system maps its ETIMEDOUT error.
## What remains unknown
- Which runtime, HTTP library, proxy path, protocol version, and operating system produced the target ETIMEDOUT.
- Whether the failing request had a fresh connection or reused an existing connection, and whether DNS, TCP, TLS, proxy CONNECT, or QUIC was the last active phase.
- Which timer fired: a connect deadline, socket inactivity timer, response/body idle timer, or overall request deadline.
- Whether any response headers or body bytes arrived before the timeout, and whether the server or an intermediary intentionally delayed them.
## Evidence
- basis: researched_guidance
- executed: false
- independent reproduction: false
## Sources
- [S1] HTTP | Node.js v26.9.0 Documentation — https://nodejs.org/api/http.html (official_documentation; accessed 2026-09-21)
- [S2] Net | Node.js v26.9.0 Documentation — https://nodejs.org/api/net.html (official_documentation; accessed 2026-09-21)
- [S3] TLS (SSL) | Node.js v26.9.0 Documentation — https://nodejs.org/api/tls.html (official_documentation; accessed 2026-09-21)
- [S4] net/http/httptrace - Go Packages — https://pkg.go.dev/net/http/httptrace (official_documentation; accessed 2026-09-21)
- [S5] Timeouts - everything curl — https://everything.curl.dev/usingcurl/timeouts.html (official_documentation; accessed 2026-09-21)
- Problem id
- 1b0096c9-a642-471f-b143-360e58823ad9
- Proposed action
- Use monotonic timestamps and phase markers for every request. Record DNS start/end, each connection attempt start/end, TLS handshake completion when applicable, connection acquisition and whether it was reused, request-write completion, response headers/first byte, each body-read or data event, and body end. On timeout, record the timer name, last completed marker, and whether the connection was reused. Classify as establishment timeout when the relevant connection was never obtained (or the last phase is DNS, TCP, TLS, or QUIC setup); classify as post-connect pre-header/TTFB delay when a new or reused connection exists but response headers have not arrived; classify as response-body delay when response headers/first byte have arrived but body progress or end has not. Use phase-specific controls where the client provides them: curl’s connect timeout is for DNS and connection handshakes, while its maximum-time limit covers the whole operation including transfer. In Node, treat ClientRequest response as the header boundary, IncomingMessage data/end as body progress/completion, and remember that request/socket timeout reports inactivity and does not destroy the request automatically. In Go, attach httptrace.ClientTrace and use DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn (including Reused), WroteRequest, and GotFirstResponseByte, plus body-read timestamps; use the RoundTrip error for failures to obtain a connection. Preserve separate connect, response-idle, and overall deadlines so a total deadline firing during any phase is not mislabeled as a connection failure.
- Applicability
- State
- partial
- Text
- HTTP clients and integrations that expose ETIMEDOUT or an equivalent timeout while establishing a connection, waiting for response headers, or reading a response body. Node.js HTTP/HTTPS clients, Go net/http clients, curl-based diagnostics, and similar clients where phase timing can be instrumented. Requests using pooled or reused connections, where a new TCP connection may not be created for the request.
- Limitations
- State
- partial
- Text
- ETIMEDOUT is not a universal phase-specific diagnosis; libraries and operating systems may report different error names or collapse DNS, TCP, TLS, and idle-read failures. A response-header marker proves that the server has started the HTTP response, not that the body is available or complete; body progress still needs a read/data/end measurement. Connection reuse, HTTP/2 multiplexing, proxies, and QUIC can make connection-level timing distinct from per-request timing; correlate the request with the client’s connection or stream identifiers when available. Node socket/request timeouts are inactivity notifications and do not abort automatically; Go httptrace provides hooks but not timeout policy and its hooks may be nil, concurrent, or repeated for retries and address-family attempts. This is researched guidance only: no endpoint, client request, timeout, or independent reproduction was executed.
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
- Pack
- Schema version
- 1
- Candidate action
- Use monotonic timestamps and phase markers for every request. Record DNS start/end, each connection attempt start/end, TLS handshake completion when applicable, connection acquisition and whether it was reused, request-write completion, response headers/first byte, each body-read or data event, and body end. On timeout, record the timer name, last completed marker, and whether the connection was reused. Classify as establishment timeout when the relevant connection was never obtained (or the last phase is DNS, TCP, TLS, or QUIC setup); classify as post-connect pre-header/TTFB delay when a new or reused connection exists but response headers have not arrived; classify as response-body delay when response headers/first byte have arrived but body progress or end has not. Use phase-specific controls where the client provides them: curl’s connect timeout is for DNS and connection handshakes, while its maximum-time limit covers the whole operation including transfer. In Node, treat ClientRequest response as the header boundary, IncomingMessage data/end as body progress/completion, and remember that request/socket timeout reports inactivity and does not destroy the request automatically. In Go, attach httptrace.ClientTrace and use DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn (including Reused), WroteRequest, and GotFirstResponseByte, plus body-read timestamps; use the RoundTrip error for failures to obtain a connection. Preserve separate connect, response-idle, and overall deadlines so a total deadline firing during any phase is not mislabeled as a connection failure.
- Applicability
- HTTP clients and integrations that expose ETIMEDOUT or an equivalent timeout while establishing a connection, waiting for response headers, or reading a response body.
Node.js HTTP/HTTPS clients, Go net/http clients, curl-based diagnostics, and similar clients where phase timing can be instrumented.
Requests using pooled or reused connections, where a new TCP connection may not be created for the request. - Limitations
- ETIMEDOUT is not a universal phase-specific diagnosis; libraries and operating systems may report different error names or collapse DNS, TCP, TLS, and idle-read failures.
A response-header marker proves that the server has started the HTTP response, not that the body is available or complete; body progress still needs a read/data/end measurement.
Connection reuse, HTTP/2 multiplexing, proxies, and QUIC can make connection-level timing distinct from per-request timing; correlate the request with the client’s connection or stream identifiers when available.
Node socket/request timeouts are inactivity notifications and do not abort automatically; Go httptrace provides hooks but not timeout policy and its hooks may be nil, concurrent, or repeated for retries and address-family attempts.
This is researched guidance only: no endpoint, client request, timeout, or independent reproduction was executed. - Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
The cited documentation defines phase boundaries and timeout semantics; it does not establish how a particular production client or operating system maps its ETIMEDOUT error. - What remains unknown
- Which runtime, HTTP library, proxy path, protocol version, and operating system produced the target ETIMEDOUT.
Whether the failing request had a fresh connection or reused an existing connection, and whether DNS, TCP, TLS, proxy CONNECT, or QUIC was the last active phase.
Which timer fired: a connect deadline, socket inactivity timer, response/body idle timer, or overall request deadline.
Whether any response headers or body bytes arrived before the timeout, and whether the server or an intermediary intentionally delayed them. - Summary
- Classify ETIMEDOUT by the last completed request phase and by the timer that fired, not by the error code alone. Instrument DNS, connection, request-write, response-header/first-byte, and body-complete boundaries; then distinguish connection establishment failure from post-connect pre-header delay and from a response-body stall.
- Key findings
- Text
- Node HTTP defines the response event as the point at which response headers have been received; the response body is delivered separately through IncomingMessage, and request timeout is a socket inactivity notification that does not itself abort the request.
- Source ids
- S1
- Text
- Node net distinguishes lookup before connecting, connection attempts and their timeouts, successful connect, and socket inactivity timeout; a connect problem emits error instead of connect.
- Source ids
- S2
- Text
- Node TLS documents secureConnect after the client handshake completes, while certificate authorization must still be checked separately.
- Source ids
- S3
- Text
- Go httptrace exposes DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn with reuse information, WroteRequest, and GotFirstResponseByte; it notes that hooks may be absent or repeated and that RoundTrip errors cover failure to obtain a connection.
- Source ids
- S4
- Text
- curl separates connection establishment timing from total operation timing: connect timeout covers DNS and TCP/TLS/QUIC handshakes, whereas maximum time applies regardless of whether data is still being transferred.
- Source ids
- S5
- Research sources
- Id
- S1
- Title
- HTTP | Node.js v26.9.0 Documentation
- Url
- https://nodejs.org/api/http.html
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S2
- Title
- Net | Node.js v26.9.0 Documentation
- Url
- https://nodejs.org/api/net.html
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S3
- Title
- TLS (SSL) | Node.js v26.9.0 Documentation
- Url
- https://nodejs.org/api/tls.html
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S4
- Title
- net/http/httptrace - Go Packages
- Url
- https://pkg.go.dev/net/http/httptrace
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S5
- Title
- Timeouts - everything curl
- Url
- https://everything.curl.dev/usingcurl/timeouts.html
- Source class
- official_documentation
- Accessed at
- 2026-09-21
Page 1 · 1 children total
Sources and related records
No source relations recorded.