Errors

undici raises typed error objects so that failures can be distinguished programmatically. Every error class is exposed through the errors namespace of the package:

import { errors } from 'undici'

if (err instanceof errors.ConnectTimeoutError) {
  // handle connect timeout
}

All errors, except HTTPParserError, extend UndiciError. Each error carries a stable code string (for example UND_ERR_CONNECT_TIMEOUT) and a name.

Because the bundled (global) dispatcher may come from a different undici version than the one you import directly, prefer matching on error.code rather than instanceof errors.UndiciError:

if (err.code === 'UND_ERR_CONNECT_TIMEOUT') {
  // handle connect timeout
}

class UndiciError extends Error

The base class for all undici errors. It is reliable with instanceof even when the error originates from a different undici version, because the check is based on a well-known symbol rather than the prototype chain.

class ConnectTimeoutError extends UndiciError

The socket was destroyed because establishing the connection exceeded the connectTimeout option.

When autoSelectFamily is enabled and every attempted address times out, Node.js raises an AggregateError. undici normalizes these multi-address timeouts into a ConnectTimeoutError so that the error shape is the same regardless of whether Node.js's per-address timer or undici's connectTimeout wins the race. The original AggregateError is preserved on error.cause.

class HeadersTimeoutError extends UndiciError

The socket was destroyed because receiving the response headers exceeded the headersTimeout option.

class HeadersOverflowError extends UndiciError

The socket was destroyed because the response headers exceeded the maximum allowed size.

class BodyTimeoutError extends UndiciError

The socket was destroyed because reading the response body exceeded the bodyTimeout option.

class InvalidArgumentError extends UndiciError

An invalid argument was passed to an undici API.

class InvalidReturnValueError extends UndiciError

A user-supplied callback or interceptor returned an invalid value.

class AbortError extends UndiciError

The operation was aborted. This is the base class of RequestAbortedError.

class RequestAbortedError extends AbortError

The request was aborted by the user, typically through an AbortSignal.

class InformationalError extends UndiciError

An expected error carrying a reason, used internally to surface a cause for a failed or retried request (for example as the cause of another error).

class RequestContentLengthMismatchError extends UndiciError

The length of the request body did not match the content-length header.

class ResponseContentLengthMismatchError extends UndiciError

The length of the response body did not match the content-length header.

class ClientDestroyedError extends UndiciError

An operation was attempted on a client that has already been destroyed.

class ClientClosedError extends UndiciError

An operation was attempted on a client that has already been closed.

class SocketError extends UndiciError

An error occurred on the underlying socket.

The socket property, when present, holds the following fields:

interface SocketInfo {
  localAddress?: string
  localPort?: number
  remoteAddress?: string
  remotePort?: number
  remoteFamily?: string
  timeout?: number
  bytesWritten?: number
  bytesRead?: number
}

class NotSupportedError extends UndiciError

Unsupported functionality was requested.

class BalancedPoolMissingUpstreamError extends UndiciError

No upstream has been added to the BalancedPool.

class HTTPParserError extends Error

An error occurred while parsing the HTTP response. Unlike the other error classes, HTTPParserError extends <Error> directly rather than UndiciError.

class ResponseExceededMaxSizeError extends UndiciError

The response body exceeded the maximum allowed size.

class RequestRetryError extends UndiciError

A request failed and could not be retried, for example because the body is stateful (a stream or AsyncIterable) and cannot be replayed.

new RequestRetryError(message, code, options): void

class ResponseError extends UndiciError

The response returned an error status code. This is raised, for example, when the throwOnError option is enabled.

new ResponseError(message, code, options): void

class SecureProxyConnectionError extends UndiciError

A TLS connection to a proxy failed.

new SecureProxyConnectionError(cause, message?, options?): void

class MaxOriginsReachedError extends UndiciError

The maximum number of allowed origins has been reached.

class Socks5ProxyError extends UndiciError

An error occurred during SOCKS5 proxy negotiation.

new Socks5ProxyError(message?, code?): void

class MessageSizeExceededError extends UndiciError

A decompressed WebSocket message exceeded the maximum allowed size.