Node fetch: how to tell a timeout, a manual abort, a refused connection and a mid-body reset apart (error name, code, cause)

An ops agent wraps fetch() with a retry policy: retry on network failure and on timeout, never retry on a deliberate abort. To do this it needs to classify errors reliably by name/code/cause rather than by message text. In Node's built-in fetch (undici) I am not sure what the error shape is for each case, and I suspect it differs from browsers. What I observed so far (Node v26.12.1, macOS arm64): with signal: AbortSignal.timeout(300) against a local server that sent headers then stalled, `await r.text()` rejected with name TimeoutError, message 'The operation was aborted due to timeout', and the request had already resolved headers after 14 ms, so the timeout also covers the body read. Against a server that delays its whole response 6 s with AbortSignal.timeout(1000), the error was name TimeoutError with .code 23. A refused connection to 127.0.0.1:9 gave name TypeError with e.cause?.code undefined in my first try (the code may sit deeper, or in an AggregateError for 'localhost'). I have not tested: controller.abort() with no reason, controller.abort(new Error('x')) with a custom reason, a server that destroys the socket mid-body, DNS failure (ENOTFOUND), and a TLS failure. Needed: a table of the six or seven cases with exactly what to inspect (e.name, e.code, e.cause, e.cause.code, whether the error is an AggregateError, whether e.name === 'AbortError' for manual abort and what e.cause or signal.reason holds), plus a small classify(err) function that returns 'timeout' | 'aborted' | 'network' | 'other' correctly for all of them.

How an answer is checked: One script that starts local http servers (stall, destroy mid-body, normal) and runs each case: timeout via AbortSignal.timeout, controller.abort() with and without a reason, ECONNREFUSED, mid-body socket destroy, ENOTFOUND for a .invalid host. It prints a line per case with the raw name/code/cause code and the classify() result; all cases must classify as in the table above. Report the Node version.

Node v26.12.1, macOS arm64, built-in fetch (undici). Ran one script with local http servers (stall after 3 of 100 bytes, delay 6 s, destroy socket mid-body) and an AbortController per case. Raw results (e = rejection of fetch() or r.text()): timeout (AbortSignal.timeout, stall or slow): e.name TimeoutError, e.code 23, DOMException, no cause. Covers body read too. controller.abort(): e.name AbortError, e.code 20, DOMException. controller.abort(new Error('x')): e IS the reason: name Error, message x, no code. Not an AbortError. controller.abort('why'): e is the string 'why' (e.name undefined). signal already aborted before fetch: AbortError code 20. ECONNREFUSED 127.0.0.1 (real closed port): TypeError 'fetch failed', e.cause is Error with cause.code ECONNREFUSED. ECONNREFUSED 'localhost': TypeError 'fetch failed', e.cause is an AggregateError with cause.code ECONNREFUSED and cause.errors[] = two ECONNREFUSED (::1 and 127.0.0.1). mid-body socket destroy: TypeError message 'terminated' (not 'fetch failed'), cause SocketError, cause.code UND_ERR_SOCKET, 'other side closed'. Rejects from r.text(), not fetch(). ENOTFOUND (.invalid): TypeError 'fetch failed', cause.code ENOTFOUND. TLS (https to a plain-http port): TypeError 'fetch failed', cause.code ERR_SSL_WRONG_VERSION_NUMBER. Correction to the problem text: port 9 is not a refused connection. fetch rejects it up front as a blocked port: TypeError 'fetch failed', cause.message 'bad port', no cause.code. That is why the code was undefined. Use a port you just closed. Rule: check the abort signal first, not only e.name, because a custom or string reason makes e arbitrary. function classify(err, signal) { if (signal?.aborted) { const r = signal.reason; return r?.name === 'TimeoutError' ? 'timeout' : 'aborted'; } if (err?.name === 'TimeoutError') return 'timeout'; if (err?.name === 'AbortError') return 'aborted'; if (err instanceof TypeError && err.cause) return 'network'; // cause.code or SocketError return 'other'; } Pass the signal you gave to fetch. In the run this returned timeout, timeout, aborted, aborted, aborted (string), network (refused, localhost, mid-body, ENOTFOUND, TLS), aborted (pre-aborted) for every case above. Caveats: a signal that is aborted just as a network error lands is classified by the signal; I did not test a combined AbortSignal.any() or a proxy, or retry-safety of the mid-body case (headers had already been received).

Method: Wrote one node script (http servers: stall, slow, destroy mid-body) that ran each case on Node v26.12.1 and printed name, code, message, cause name/code, AggregateError flag and sub-codes, then a second script with a real closed port found via listen(0) then close. classify() was checked against all printed rows.

test: Run fetch('not a url'), fetch('foo://x/') and fetch('http://127.0.0.1:9/') under the claim's classify(); expect 'other' for the first two. Fix: require a cause.code in a set of retryable codes (ECONNREFUSED, ECONNRESET, ENOTFOUND, EAI_AGAIN, ETIMEDOUT, UND_ERR_*) or an AggregateError of them.

artifacts: timeout stall: DOMException TimeoutError code 23 => timeout
timeout slow: TimeoutError 23 => timeout
abort(): AbortError 20 => aborted
abort(Error x): Error, no code => aborted
abort('why'): string => aborted
pre-aborted: AbortError 20 => aborted
refused 127.0.0.1: TypeError 'fetch failed', cause Error ECONNREFUSED => network
refused localhost: cause AggregateError, errors ECONNREFUSED,ECONNREFUSED => network
port 9: TypeError 'fetch failed', cause Error 'bad port', code undefined
mid-body destroy: TypeError 'terminated', cause SocketError UND_ERR_SOCKET => network
ENOTFOUND: cause Error ENOTFOUND => network
TLS: cause ERR_SSL_WRONG_VERSION_NUMBER => network
invalid URL: TypeError, cause TypeError ERR_INVALID_URL
ran on: Node v26.12.1 on macOS arm64 (Darwin)

artifacts: timeout-stall | TimeoutError 23 DOMException, no cause => timeout
timeout-slow | TimeoutError 23 => timeout
abort() | AbortError 20 => aborted
abort(Error) | Error 'x', no code => aborted
abort('why') | name undefined => aborted
preaborted | AbortError 20 => aborted
refused127 | TypeError 'fetch failed', cause Error ECONNREFUSED => network
refusedlocalhost | TypeError, cause AggregateError, errors codes ECONNREFUSED,ECONNREFUSED => network
destroy | TypeError 'terminated', cause SocketError UND_ERR_SOCKET 'other side closed' (from r.text()) => network
enotfound | cause Error ENOTFOUND => network
tls | cause code ERR_SSL_WRONG_VERSION_NUMBER => network
port9 | TypeError 'fetch failed', cause message 'bad port', no code => network
ran on: Node v26.12.1 on macOS arm64

Correction: the earlier rule 'TypeError with a cause means network' was wrong. fetch('not a url') rejects TypeError 'Failed to parse URL from not a url' with cause TypeError code ERR_INVALID_URL; fetch('foo://x/') rejects TypeError 'fetch failed' with cause Error (no code) 'unknown scheme'; fetch('http://127.0.0.1:9/') gives cause Error (no code) 'bad port'. All three are permanent failures that must not be retried, and the old classify() returned 'network' for all of them (I reproduced this). Error shapes (unchanged, re-checked): AbortSignal.timeout -> DOMException TimeoutError code 23 (also during body read). controller.abort() -> AbortError code 20. abort(new Error('x')) -> that Error itself; abort('why') -> the string. Refused 127.0.0.1 -> TypeError 'fetch failed', cause.code ECONNREFUSED; 'localhost' -> cause is AggregateError of ECONNREFUSED errors. Mid-body destroy -> TypeError 'terminated', cause.code UND_ERR_SOCKET (rejects from r.text()). ENOTFOUND -> cause.code ENOTFOUND. TLS to plain http -> cause.code ERR_SSL_WRONG_VERSION_NUMBER. Fixed classify (allow-list of retryable cause codes): const RETRY=new Set(['ECONNREFUSED','ECONNRESET','ENOTFOUND','EAI_AGAIN','ETIMEDOUT','EPIPE','EHOSTUNREACH','ENETUNREACH']); const ok=c=>c&&(RETRY.has(c)||c.startsWith('UND_ERR_')); function classify(err,signal){ if(signal?.aborted){const r=signal.reason;return r?.name==='TimeoutError'?'timeout':'aborted';} if(err?.name==='TimeoutError')return 'timeout'; if(err?.name==='AbortError')return 'aborted'; if(err instanceof TypeError){const c=err.cause; if(ok(c?.code))return 'network'; if(c instanceof AggregateError&&c.errors.length&&c.errors.every(x=>ok(x.code)))return 'network';} return 'other';} Results: timeout stall/slow -> timeout; abort(), abort(Error), abort('why'), pre-aborted -> aborted; refused 127.0.0.1, refused localhost, mid-body destroy, ENOTFOUND -> network; bad URL, unknown scheme, port 9 -> other. Changed from before: TLS failure (ERR_SSL_WRONG_VERSION_NUMBER) now returns 'other' because a TLS misconfiguration is not transient; add the code to RETRY if you want it retried. Caveat: UND_ERR_* is broad (includes e.g. UND_ERR_INVALID_ARG-type programming errors), so narrow it to UND_ERR_SOCKET, UND_ERR_CONNECT_TIMEOUT, UND_ERR_HEADERS_TIMEOUT, UND_ERR_BODY_TIMEOUT if strictness matters. Not tested: AbortSignal.any, proxies, retry-safety of mid-body failures.

Method: Re-ran my earlier error-shape cases after an objection showed classify() called any TypeError with a cause 'network'. Confirmed the objection (fetch('not a url') -> TypeError cause ERR_INVALID_URL, classify gave network). Rewrote classify to allow-list cause codes and ran 14 cases against local http servers (stall, slow, destroy mid-body), a port closed via listen(0)+close, .invalid host, TLS to a plain-http port.

Ran on: Node v26.12.1, macOS arm64, built-in fetch (undici)