Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fetch
✓ import { fetch } from 'undici';
✗ const { fetch } = require('undici');
While CommonJS might work for some exports, explicit ESM imports are recommended for modern Node.js development, especially with the `fetch` API. Undici requires Node.js >=22.19.0, which fully supports ESM.
Client
✓ import { Client } from 'undici';
Agent
✓ import { Agent } from 'undici';
Demonstrates how to perform a basic GET request using undici's `fetch` API and log the JSON response. This example fetches information about the 'nodejs' user from GitHub.
import { fetch } from 'undici';
async function fetchData() {
try {
const response = await fetch('https://api.github.com/users/nodejs', {
headers: {
'User-Agent': 'undici-example/1.0',
},
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log('GitHub user:', data.login);
} catch (error) {
console.error('Failed to fetch data:', error);
}
}
fetchData();
Debug
Known issues
breakingUndici v8.0.0 enabled HTTP/2 (H2) by default and removed legacy handler wrappers, which can affect applications that relied on specific HTTP/1.1 behaviors or older API patterns.fixConsult the official Undici 7 to 8 migration guide for detailed instructions on adapting existing code and configuring HTTP/1.1 if needed.
affects: >=8.0.0
gotchaUndici requires Node.js version 22.19.0 or higher. Running on older Node.js versions may lead to syntax errors or missing API features due to its use of modern JavaScript features like `Promise.withResolvers()`.fixUpgrade your Node.js environment to version 22.19.0 or later.
affects: <22.19.0 (Node.js)
gotchaWhen using `fetch`, ensure the URL is absolute and includes a scheme (e.g., `https://example.com`). Providing a relative path or missing scheme will result in a `TypeError: Not a valid URL`.fixAlways provide a complete and absolute URL, for instance, `await fetch('https://example.com/api')`. affects: *
deprecatedDirect use of `globalThis.fetch` or `globalThis.Request` etc. provided by `undici/global` should be avoided in favor of explicit imports (`import { fetch } from 'undici';`). `undici/global` is primarily for compatibility layers and may not be actively maintained for new features in future major versions.fixImport `fetch`, `Request`, `Response`, etc., directly from `undici`.
affects: *
Errors
Common errors & fixes
TypeError: fetch is not a function
`fetch` was not imported or not made globally available, or an outdated Node.js version is used that doesn't provide global fetch and `undici/global` wasn't used.
fixEnsure `import { fetch } from 'undici';` is at the top of your file. If you need global availability (e.g., for compatibility), `import 'undici/global';` once in your application entry point. TypeError [ERR_INVALID_URL]: Invalid URL
The URL provided to `fetch` or `Client` is not absolute or lacks a scheme (e.g., `http://` or `https://`).
fixProvide a full, absolute URL, including the scheme (e.g., `https://api.example.com/data`).
Error: This API is not available on Node.js <= 20
Your current Node.js version does not meet undici's minimum engine requirement (>=22.19.0), or a specific feature like `Promise.withResolvers()` is used which is only available in newer Node.js versions.
fixUpgrade your Node.js environment to version 22.19.0 or later.
ERR_HTTP_INVALID_HEADER_VALUE
An HTTP header value contains invalid characters or is incorrectly formatted according to HTTP/1.1 or HTTP/2 specifications (e.g., newlines).
fixValidate header values to ensure they conform to RFC standards and do not contain disallowed characters or formatting.
Error: Undici encountered a parse error: Invalid response status code
The remote server returned an invalid or malformed HTTP response status line or header, which undici cannot parse.
fixThis typically indicates an issue with the remote server. Verify the server's response format or report the issue to the server maintainers.
Audit
Dependencies
No dependency data recorded yet.