`npm run test:wpt` and `node test/web-platform-tests/wpt-runner.mjs setup` will initialize the WPT submodule automatically when it is missing.

If you want to prepare the checkout explicitly, run:

git submodule update --init --recursive

const data = await body.json();

When you send a `FormData` body, keep `fetch` and `FormData` from the same

implementation.

Use one of these patterns:

const body = new FormData()

body.set('name', 'some')

await fetch('https://example.com', {

method: 'POST',

body

})

import { fetch, FormData } from 'undici'

const body = new FormData()

body.set('name', 'some')

await fetch('https://example.com', {

method: 'POST',

body

})

If you want the installed `undici` package to provide the globals, call

`install()` first:

import { install } from 'undici'

install()

const body = new FormData()

body.set('name', 'some')

await fetch('https://example.com', {

method: 'POST',

body

})

`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and

`FormData` implementations with undici's versions, so they all match.

Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`

with the built-in global `fetch()`.

You can check which version of undici is bundled with your Node.js version:

- `CloseEvent`, `ErrorEvent`, `MessageEvent` - WebSocket events

- `EventSource` - Server-sent events client

When you call `install()`, these globals come from the same undici

implementation. For example, global `fetch` and global `FormData` will both be

undici's versions, which is the recommended setup if you want to use undici

through globals.

This is useful for:

- Polyfilling environments that don't have fetch

- Ensuring consistent fetch behavior across different Node.js versions

Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,

including undici that is bundled internally with node.js.

Undici stores this dispatcher under `Symbol.for('undici.globalDispatcher.2')`.

`setGlobalDispatcher()` also mirrors the configured dispatcher to

`Symbol.for('undici.globalDispatcher.1')` using `Dispatcher1Wrapper`, so Node.js built-in `fetch`

can keep using the legacy handler contract while Undici uses the new handler API.

Gets the global dispatcher used by Common API Methods.

* **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. **Security Warning:** Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.

* **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.

* **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.

* **allowH2**: `boolean` - Default: `true`. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.

* **useH2c**: `boolean` - Default: `false`. Enforces h2c for non-https connections.

* **maxConcurrentStreams**: `number` - Default: `100`. Dictates the maximum number of concurrent streams for a single H2 session. It can be overridden by a SETTINGS remote frame.

* **initialWindowSize**: `number` (optional) - Default: `262144` (256KB). Sets the HTTP/2 stream-level flow-control window size (SETTINGS_INITIAL_WINDOW_SIZE). Must be a positive integer greater than 0. This default is higher than Node.js core's default (65535 bytes) to improve throughput, Node's choice is very conservative for current high-bandwith networks. See [RFC 7540 Section 6.9.2](https://datatracker.ietf.org/doc/html/rfc7540#section-6.9.2) for more details.

Invoked for user errors such as throwing in the `onResponseError` handler.

console.log(websocket) // the WebSocket instance

// Handshake response details

console.log(handshakeResponse.status) // 101 for HTTP/1.1, 200 for HTTP/2 extended CONNECT

console.log(handshakeResponse.statusText) // 'Switching Protocols' for HTTP/1.1, commonly 'OK' for HTTP/2 in Node.js

console.log(handshakeResponse.headers) // Object containing response headers

})

The `handshakeResponse` object contains the HTTP response that established the WebSocket connection:

- `status` (number): The HTTP status code (`101` for HTTP/1.1 upgrade, `200` for HTTP/2 extended CONNECT)

- `statusText` (string): The HTTP status message (`'Switching Protocols'` for HTTP/1.1, commonly `'OK'` for HTTP/2 in Node.js)

- `headers` (object): The HTTP response headers from the server, including:

- `sec-websocket-accept` and other WebSocket-related headers

- `upgrade: 'websocket'`

- `connection: 'upgrade'`

The `upgrade` and `connection` headers are only present for HTTP/1.1 handshakes.

This information is particularly useful for debugging and monitoring WebSocket connections, as it provides access to the initial HTTP handshake response that established the WebSocket connection.

* **onResponseEnd** `(controller: DispatchController, trailers: Record<string, string | string[]>) => void` - Invoked when response payload and trailers have been received and the request has completed. Not required for `upgrade` requests.

* **onResponseError** `(controller: DispatchController, error: Error) => void` - Invoked when an error has occurred. May not throw.

If you were previously using `onConnect/onHeaders/onData/onComplete/onError`, switch to the new callbacks:

- `onConnect(abort)` → `onRequestStart(controller)` and call `controller.abort(reason)`

- `onHeaders(status, rawHeaders, resume, statusText)` → `onResponseStart(controller, status, headers, statusText)`

- `onData(chunk)` → `onResponseData(controller, chunk)`

- `onComplete(trailers)` → `onResponseEnd(controller, trailers)`

- `onError(err)` → `onResponseError(controller, err)`

- `onUpgrade(status, rawHeaders, socket)` → `onRequestUpgrade(controller, status, headers, socket)`

To access raw header arrays (for preserving duplicates/casing), read them from the controller:

- `controller.rawHeaders` for response headers

- `controller.rawTrailers` for trailers

Pause/resume now uses the controller:

- Call `controller.pause()` and `controller.resume()` instead of returning `false` from handlers.

Undici now stores the global dispatcher under `Symbol.for('undici.globalDispatcher.2')`.

This avoids conflicts with runtimes (such as Node.js built-in `fetch`) that still rely on the legacy dispatcher handler interface.

`setGlobalDispatcher()` also mirrors the configured dispatcher to `Symbol.for('undici.globalDispatcher.1')` using a `Dispatcher1Wrapper`, so Node's built-in `fetch` can keep using the legacy handler contract.

If you need to expose a new dispatcher/agent to legacy v1 handler consumers (`onConnect/onHeaders/onData/onComplete/onError/onUpgrade`), use `Dispatcher1Wrapper`:

import { Agent, Dispatcher1Wrapper } from 'undici'

const legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())

'x-foo': 'bar'

}

}, {

onRequestStart: () => {

console.log('Connected!')

},

onResponseError: (_controller, error) => {

console.error(error)

},

onResponseStart: (_controller, statusCode, headers) => {

console.log(`onResponseStart | statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)

},

onResponseData: (_controller, chunk) => {

console.log('onResponseData: chunk received')

data.push(chunk)

},

onResponseEnd: (_controller, trailers) => {

console.log(`onResponseEnd | trailers: ${JSON.stringify(trailers)}`)

const res = Buffer.concat(data).toString('utf8')

console.log(`Data: ${res}`)

client.close()

method: 'GET',

upgrade: 'websocket'

}, {

onRequestStart: () => {

console.log('Undici Client - onRequestStart')

},

onResponseError: () => {

console.log('onResponseError') // shouldn't print

},

onRequestUpgrade: (_controller, statusCode, headers, socket) => {

console.log('Undici Client - onRequestUpgrade')

console.log(`onRequestUpgrade Headers: ${JSON.stringify(headers)}`)

socket.on('data', buffer => {

console.log(buffer.toString('utf8'))

})

},

body: JSON.stringify({ message: 'Hello' })

}, {

onRequestStart: () => {

console.log('Connected!')

},

onResponseError: (_controller, error) => {

console.error(error)

},

onResponseStart: (_controller, statusCode, headers) => {

console.log(`onResponseStart | statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)

},

onResponseData: (_controller, chunk) => {

console.log('onResponseData: chunk received')

data.push(chunk)

},

onResponseEnd: (_controller, trailers) => {

console.log(`onResponseEnd | trailers: ${JSON.stringify(trailers)}`)

const res = Buffer.concat(data).toString('utf8')

console.log(`Response Data: ${res}`)

client.close()

For easy use with [stream.pipeline](https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-options). The `handler` argument should return a `Readable` from which the result will be read. Usually it should just return the `body` argument unless some kind of transformation needs to be performed based on e.g. `headers` or `statusCode`. The `handler` should validate the response and save any required state. If there is an error, it should be thrown. The function returns a `Duplex` which writes to the request and reads from the response.

Arguments:

const { redirect } = interceptors;

const client = new Client("http://service.example").compose(

redirect({ maxRedirections: 3, throwOnMaxRedirect: true })

);

client.request({ path: "/" })

- `dualStack` - Whether to resolve both IPv4 and IPv6 addresses. Default: `true`.

- It will also attempt a happy-eyeballs-like approach to connect to the available addresses in case of a connection failure.

- `affinity` - Whether to use IPv4 or IPv6 addresses. Default: `4`.

- It can be either `4` or `6`.

- It will only take effect if `dualStack` is `false`.

- `lookup: (hostname: string, options: LookupOptions, callback: (err: NodeJS.ErrnoException | null, addresses: DNSInterceptorRecord[]) => void) => void` - Custom lookup function. Default: `dns.lookup`.

- For more info see [dns.lookup](https://nodejs.org/api/dns.html#dnslookuphostname-options-callback).

- `pick: (origin: URL, records: DNSInterceptorRecords, affinity: 4 | 6) => DNSInterceptorRecord` - Custom pick function. Default: `RoundRobin`.

- The function should return a single record from the records array.

- By default a simplified version of Round Robin is used.

If any parameters are passed to the FormData constructor other than `undefined`, an error will be thrown. Other parameters are ignored.

When you use `FormData` as a request body, keep `fetch` and `FormData` from the

same implementation. Use the built-in global `FormData` with the built-in

global `fetch()`, and use `undici`'s `FormData` with `undici.fetch()`.

If you want the installed `undici` package to provide the globals, call

[`install()`](/docs/api/GlobalInstallation.md) so `fetch`, `Headers`,

`Response`, `Request`, and `FormData` are installed together as a matching set.

This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)

| `MessageEvent` | WebSocket message event |

| `EventSource` | Server-sent events client |

If you send a `FormData` body, use matching implementations for `fetch` and

`FormData`.

These two patterns are safe:

const body = new FormData()

await fetch('https://example.com', {

method: 'POST',

body

})

import { install } from 'undici'

install()

const body = new FormData()

await fetch('https://example.com', {

method: 'POST',

body

})

After `install()`, `fetch`, `Headers`, `Response`, `Request`, and `FormData`

all come from the installed `undici` package, so they work as a matching set.

If you do not want to install globals, import both from `undici` instead:

import { fetch, FormData } from 'undici'

const body = new FormData()

await fetch('https://example.com', {

method: 'POST',

body

})

Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`

with the built-in global `fetch()`. Keeping them paired avoids surprising

multipart behavior across Node.js and undici versions.

Global installation is useful for:

Invoked for user errors such as throwing in the `onResponseError` handler.