{"id":10427,"library":"undici","title":"Undici","description":"Undici is a powerful HTTP/1.1 client written from scratch for Node.js, offering a modern API including a WHATWG `fetch` implementation. It is currently at version 8.1.0, with frequent patch and minor releases across its active major versions, often aligning with Node.js LTS cycles.","status":"active","version":"8.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/nodejs/undici","tags":["javascript","fetch","http","https","promise","request","curl","wget","xhr","typescript"],"install":[{"cmd":"npm install undici","lang":"bash","label":"npm"},{"cmd":"yarn add undici","lang":"bash","label":"yarn"},{"cmd":"pnpm add undici","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { fetch } = require('undici');","symbol":"fetch","correct":"import { fetch } from 'undici';"},{"symbol":"Client","correct":"import { Client } from 'undici';"},{"symbol":"Agent","correct":"import { Agent } from 'undici';"}],"quickstart":{"code":"import { fetch } from 'undici';\n\nasync function fetchData() {\n  try {\n    const response = await fetch('https://api.github.com/users/nodejs', {\n      headers: {\n        'User-Agent': 'undici-example/1.0',\n      },\n    });\n\n    if (!response.ok) {\n      throw new Error(`HTTP error! status: ${response.status}`);\n    }\n\n    const data = await response.json();\n    console.log('GitHub user:', data.login);\n  } catch (error) {\n    console.error('Failed to fetch data:', error);\n  }\n}\n\nfetchData();","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult the official Undici 7 to 8 migration guide for detailed instructions on adapting existing code and configuring HTTP/1.1 if needed.","message":"Undici 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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Upgrade your Node.js environment to version 22.19.0 or later.","message":"Undici 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()`.","severity":"gotcha","affected_versions":"<22.19.0 (Node.js)"},{"fix":"Always provide a complete and absolute URL, for instance, `await fetch('https://example.com/api')`.","message":"When 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`.","severity":"gotcha","affected_versions":"*"},{"fix":"Import `fetch`, `Request`, `Response`, etc., directly from `undici`.","message":"Direct 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.","severity":"deprecated","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Ensure `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.","cause":"`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.","error":"TypeError: fetch is not a function"},{"fix":"Provide a full, absolute URL, including the scheme (e.g., `https://api.example.com/data`).","cause":"The URL provided to `fetch` or `Client` is not absolute or lacks a scheme (e.g., `http://` or `https://`).","error":"TypeError [ERR_INVALID_URL]: Invalid URL"},{"fix":"Upgrade your Node.js environment to version 22.19.0 or later.","cause":"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.","error":"Error: This API is not available on Node.js <= 20"},{"fix":"Validate header values to ensure they conform to RFC standards and do not contain disallowed characters or formatting.","cause":"An HTTP header value contains invalid characters or is incorrectly formatted according to HTTP/1.1 or HTTP/2 specifications (e.g., newlines).","error":"ERR_HTTP_INVALID_HEADER_VALUE"},{"fix":"This typically indicates an issue with the remote server. Verify the server's response format or report the issue to the server maintainers.","cause":"The remote server returned an invalid or malformed HTTP response status line or header, which undici cannot parse.","error":"Error: Undici encountered a parse error: Invalid response status code"}],"ecosystem":"npm"}