Errors

Undici exposes a variety of error objects that you can use to enhance your error handling. You can find all the error objects inside the errors key.

import { errors } from 'undici'

Error	Error Codes	Description
`UndiciError`	`UND_ERR`	all errors below are extended from `UndiciError`.
`ConnectTimeoutError`	`UND_ERR_CONNECT_TIMEOUT`	socket is destroyed due to connect timeout.
`HeadersTimeoutError`	`UND_ERR_HEADERS_TIMEOUT`	socket is destroyed due to headers timeout.
`HeadersOverflowError`	`UND_ERR_HEADERS_OVERFLOW`	socket is destroyed due to headers' max size being exceeded.
`BodyTimeoutError`	`UND_ERR_BODY_TIMEOUT`	socket is destroyed due to body timeout.
`InvalidArgumentError`	`UND_ERR_INVALID_ARG`	passed an invalid argument.
`InvalidReturnValueError`	`UND_ERR_INVALID_RETURN_VALUE`	returned an invalid value.
`RequestAbortedError`	`UND_ERR_ABORTED`	the request has been aborted by the user
`ClientDestroyedError`	`UND_ERR_DESTROYED`	trying to use a destroyed client.
`ClientClosedError`	`UND_ERR_CLOSED`	trying to use a closed client.
`SocketError`	`UND_ERR_SOCKET`	there is an error with the socket.
`NotSupportedError`	`UND_ERR_NOT_SUPPORTED`	encountered unsupported functionality.
`RequestContentLengthMismatchError`	`UND_ERR_REQ_CONTENT_LENGTH_MISMATCH`	request body does not match content-length header
`ResponseContentLengthMismatchError`	`UND_ERR_RES_CONTENT_LENGTH_MISMATCH`	response body does not match content-length header
`InformationalError`	`UND_ERR_INFO`	expected error with reason
`ResponseExceededMaxSizeError`	`UND_ERR_RES_EXCEEDED_MAX_SIZE`	response body exceed the max size allowed
`SecureProxyConnectionError`	`UND_ERR_PRX_TLS`	tls connection to a proxy failed
`MessageSizeExceededError`	`UND_ERR_WS_MESSAGE_SIZE_EXCEEDED`	WebSocket decompressed message exceeded the maximum allowed size
`AbortError`	`UND_ERR_ABORT`	the operation was aborted (base class of `RequestAbortedError`).
`RequestRetryError`	`UND_ERR_REQ_RETRY`	request failed and could not be retried; carries `statusCode`, `headers` and `data`.
`ResponseError`	`UND_ERR_RESPONSE`	response returned an error status code; carries `statusCode`, `headers` and `body`.
`MaxOriginsReachedError`	`UND_ERR_MAX_ORIGINS_REACHED`	the maximum number of allowed origins has been reached.
`BalancedPoolMissingUpstreamError`	`UND_ERR_BPL_MISSING_UPSTREAM`	no upstream has been added to the `BalancedPool`.
`Socks5ProxyError`	`UND_ERR_SOCKS5`	an error occurred during SOCKS5 proxy negotiation.
`HTTPParserError`	`HPE_*`	an error occurred while parsing the HTTP response (extends `Error`, not `UndiciError`).

Be aware of the possible difference between the global dispatcher version and the actual undici version you might be using. We recommend to avoid the check instanceof errors.UndiciError and seek for the error.code === '<error_code>' instead to avoid inconsistencies.

`ConnectTimeoutError`

When autoSelectFamily is enabled and every attempted address fails with a timeout, Node raises an AggregateError. Undici surfaces these multi-address timeouts as ConnectTimeoutError (so the error shape is the same regardless of whether Node's family-attempt timer or undici's connectTimeout wins the race); the original AggregateError is preserved on error.cause.

`SocketError`

The SocketError has a .socket property which holds socket metadata:

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

TypeScript

Be aware that in some cases the .socket property can be null.