Undici

Common errors

• TypeError: fetch is not a function

  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.
  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.

• TypeError [ERR_INVALID_URL]: Invalid URL

  cause The URL provided to `fetch` or `Client` is not absolute or lacks a scheme (e.g., `http://` or `https://`).
  fix Provide a full, absolute URL, including the scheme (e.g., `https://api.example.com/data`).

• Error: This API is not available on Node.js <= 20

  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.
  fix Upgrade your Node.js environment to version 22.19.0 or later.

• ERR_HTTP_INVALID_HEADER_VALUE

  cause An HTTP header value contains invalid characters or is incorrectly formatted according to HTTP/1.1 or HTTP/2 specifications (e.g., newlines).
  fix Validate 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

  cause The remote server returned an invalid or malformed HTTP response status line or header, which undici cannot parse.
  fix This typically indicates an issue with the remote server. Verify the server's response format or report the issue to the server maintainers.

Warnings

• breaking 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.
  Fix: Consult the official Undici 7 to 8 migration guide for detailed instructions on adapting existing code and configuring HTTP/1.1 if needed.
• gotcha 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()`.
  Fix: Upgrade your Node.js environment to version 22.19.0 or later.
• gotcha 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`.
  Fix: Always provide a complete and absolute URL, for instance, `await fetch('https://example.com/api')`.
• deprecated 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.
  Fix: Import `fetch`, `Request`, `Response`, etc., directly from `undici`.

Install

• npm install undici npm
• yarn add undici yarn
• pnpm add undici pnpm

Imports

• fetch
  wrong:

  const { fetch } = require('undici');

  correct:

  import { fetch } from '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';

Quickstart

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();