HTTP Cookie Agent

Common errors

• Error: Cannot find package 'tough-cookie' imported from ...

  cause The `tough-cookie` peer dependency is not installed.
  fix Run `npm install tough-cookie` in your project directory.

• TypeError: fetch is not a function

  cause This usually indicates that `undici` is not installed, or the Node.js version being used does not natively provide global `fetch` without `undici`.
  fix Run `npm install undici` and ensure you are on a compatible Node.js version (>=20.0.0). If you're on Node.js 20+, `fetch` should be global once `undici` is installed, or you can `import { fetch } from 'undici';`.

• TypeError: CookieAgent is not a constructor

  cause Attempting to `require` the `CookieAgent` or other ESM-only exports in a CommonJS context, or using an incorrect import path.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements. Verify the correct import path, such as `import { CookieAgent } from 'http-cookie-agent/undici';`.

• Error: `dispatcher` must be an instance of `Dispatcher`.

  cause When using `undici` or Node.js global fetch, the `dispatcher` option expects an instance of an `undici` dispatcher. This error often arises if `CookieAgent` is not correctly instantiated or passed.
  fix Ensure you are passing an instance of `CookieAgent` to the `dispatcher` option, e.g., `new CookieAgent({ cookies: { jar } })`. Do not pass the class itself or an uninitialized object.

Warnings

• breaking Version 7.0.0 introduced breaking changes. Users upgrading from v6 should consult the `MIGRATION.md` file in the GitHub repository for detailed instructions.
  Fix: Refer to the `MIGRATION.md` guide on the `http-cookie-agent` GitHub repository to understand the necessary code adjustments for v7.x.
• gotcha This package has peer dependencies (`tough-cookie` and `undici`) that must be installed separately. Failing to install them will result in runtime errors.
  Fix: Ensure `tough-cookie` is installed (`npm install tough-cookie`). For `fetch` or `undici` usage, also install `undici` (`npm install undici`). Check the `http-cookie-agent` README for recommended `undici` versions based on your Node.js version.
• gotcha `http-cookie-agent` explicitly does not support Bun's and Deno's proprietary `fetch` implementations due to their differing internal structures.
  Fix: This library is designed for Node.js environments. For Bun or Deno, consider their native cookie handling capabilities or alternative libraries designed for those runtimes.
• breaking The `async_UNSTABLE` option was removed in version 6.0.4 due to incorrect functionality. Code relying on this option will no longer work.
  Fix: Remove the `async_UNSTABLE` option from your `CookieAgent` configuration. Review alternative asynchronous cookie handling strategies if this feature was critical to your use case.
• gotcha Node.js global `fetch` support relies on `undici`. The required `undici` version might vary depending on your Node.js version (e.g., `undici@6` for Node.js 20/22/23, `undici@7` for Node.js 24).
  Fix: Install the correct `undici` version matching your Node.js environment as specified in the `http-cookie-agent` documentation (e.g., `npm install undici@7`).
• gotcha This library requires Node.js version 20.0.0 or higher. Running on older Node.js versions will lead to compatibility issues or errors.
  Fix: Upgrade your Node.js environment to version 20.0.0 or newer. If you need to support older Node.js versions, consider using an older major version of `http-cookie-agent` that supports your target Node.js runtime, if available.

Install

• npm install http-cookie-agent npm
• yarn add http-cookie-agent yarn
• pnpm add http-cookie-agent pnpm

Imports

• CookieJar
  wrong:

  const { CookieJar } = require('tough-cookie');

  correct:

  import { CookieJar } from 'tough-cookie';

  CookieJar is the core cookie management class from the `tough-cookie` peer dependency.
• CookieAgent
  wrong:

  const { CookieAgent } = require('http-cookie-agent/undici');
  import { CookieAgent } from 'http-cookie-agent';

  correct:

  import { CookieAgent } from 'http-cookie-agent/undici';

  The primary agent for `undici` based clients (including Node.js global fetch). Be mindful of specific `undici` versions, e.g., `/undici/v6` for older Node.js versions.
• HttpsCookieAgent
  wrong:

  import { CookieAgent } from 'http-cookie-agent/http';

  correct:

  import { HttpsCookieAgent } from 'http-cookie-agent/http';

  Use `HttpsCookieAgent` or `HttpCookieAgent` from `http-cookie-agent/http` for native `node:https` and `node:http` modules, respectively.
• cookie (undici interceptor)
  wrong:

  import { CookieAgent } from 'http-cookie-agent/undici';

  correct:

  import { cookie } from 'http-cookie-agent/undici';

  This named export provides an `undici` interceptor function, which is an alternative to using `CookieAgent` directly for `undici`'s `Agent` composition pattern.

Quickstart

Demonstrates how to initialize `CookieJar` and `CookieAgent` for `undici` (or Node.js global `fetch`), making two requests to `httpbin.org` to set and then retrieve a cookie.

import { CookieJar } from 'tough-cookie';
import { CookieAgent } from 'http-cookie-agent/undici';
import { fetch } from 'undici'; // Or use global fetch if undici is installed for Node.js >=20

async function makeRequestWithCookies() {
  const jar = new CookieJar();
  const agent = new CookieAgent({ cookies: { jar } });

  console.log('Sending first request to set a cookie...');
  const firstResponse = await fetch('https://httpbin.org/cookies/set?mycookie=myvalue', {
    dispatcher: agent
  });
  console.log(`First request status: ${firstResponse.status}`);
  await firstResponse.text(); // Consume body to ensure cookies are processed

  console.log('Sending second request to retrieve the cookie...');
  const secondResponse = await fetch('https://httpbin.org/cookies', {
    dispatcher: agent
  });
  console.log(`Second request status: ${secondResponse.status}`);
  const cookieData = await secondResponse.json();
  console.log('Cookies received in second request:', cookieData.cookies);

  if (cookieData.cookies.mycookie === 'myvalue') {
    console.log('Success: Cookie was correctly sent and received!');
  } else {
    console.log('Failure: Cookie was not handled as expected.');
  }
}

makeRequestWithCookies().catch(console.error);