Does the globalDispatcher symbol need to be updated?

[KarlGe]

Hello! Trying to step carefully here because it's a bit hard to narrow this down.

We're running into a problem with using JSDOM through Vitest, and in the end I think this needs to be solved in Vitest, probably.

I'm on Node: 22.13.1
Using jsdom: 28.0.0
which depends on undici: 7.20.0

The error I was originally getting is

InvalidArgumentError: invalid onError method
 ❯ Agent.dispatch node:internal/deps/undici/undici:591:19
 ❯ innerDispatch node_modules/jsdom/lib/jsdom/browser/resources/jsdom-dispatcher.js:573:35
 ❯ node_modules/jsdom/lib/jsdom/browser/resources/decompress-interceptor.js:179:14
 ❯ innerDispatch node_modules/jsdom/lib/jsdom/browser/resources/jsdom-dispatcher.js:580:61
 ❯ node_modules/jsdom/lib/jsdom/browser/resources/jsdom-dispatcher.js:478:7
 ❯ JSDOMDispatcher.#doSingleRequest node_modules/jsdom/lib/jsdom/browser/resources/jsdom-dispatcher.js:471:12
 ❯ JSDOMDispatcher.#dispatchHTTP node_modules/jsdom/lib/jsdom/browser/resources/jsdom-dispatcher.js:265:49
 ❯ JSDOMDispatcher.dispatch node_modules/jsdom/lib/jsdom/browser/resources/jsdom-dispatcher.js:92:23
 ❯ node_modules/jsdom/lib/jsdom/living/xhr/xhr-utils.js:158:16

But it might still be relevant here, the problem happens in the unwrap-handler
https://github.com/nodejs/undici/blob/main/lib/handler/unwrap-handler.js#L90

So it's using the node:internal version of undici (6.21.0 in Node 22.13.1), which seemed weird to me. I think probably what is happening is that Vitest overrides the global fetch to use Node's version, which then triggers setGlobalDispatcher here https://github.com/nodejs/undici/blob/main/lib/global.js#L5 so then when jsdom tries using a global dispatcher from a newer version of undici, it gets the one that's already defined

So again, we'll figure out exactly how to solve this for our case (upgrading Node works just fine), but I'm wondering if this means that the globalDispatcher symbol name should be updated so that it's more resilient to version mismatches like this?

Update: See repro below, in our case it's probably Axios that makes this happen, not Vitest, but it can be reproduced by just using fetch before importing JSDOM

[mcollina]

cc @domenic ping

[KarlGe]

I think I've finally found the most concise way to demonstrate this with no other dependencies

{
  "name": "test-node-jsdom",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "jsdom": "^28.0.0"
  },
  "type": "module"
}

const url = "https://api.restful-api.dev/objects";

console.log(process.versions.undici);
const response = await fetch(url);
const data = await response.json();

let { JSDOM } = await import("jsdom");

JSDOM.fromURL("localhost:3000/test").then((dom) => {
  console.log(dom);
});

And I want to re-iterate that I don't think this is necessarily a problem with jsdom, but that this problem with the global dispatcher could probably pop up in other scenarios as well.

[domenic]

Thanks @KarlGe for the very helpful reproduction case.

Claude's analysis seems pretty accurate here:

Root cause

The issue is a cross-version global dispatcher contamination between Node's built-in undici (v6) and jsdom's external undici (v7).

Both versions share state via Symbol.for('undici.globalDispatcher.1') (line 5 of node_modules/undici/lib/global.js). The symbol name includes a version counter that's supposed to be bumped on breaking changes, but wasn't bumped between v6 and v7 despite breaking changes to the handler/dispatcher interface.

Here's the sequence of events in the reproduction case:

1. await fetch(...) triggers Node's built-in undici v6, which runs its global.js and creates a v6 Agent stored at globalThis[Symbol.for('undici.globalDispatcher.1')]
2. await import("jsdom") loads external undici v7, whose global.js also runs — but since getGlobalDispatcher() !== undefined (it was set in step 1), it skips creating a new Agent. The v6 Agent remains.
3. JSDOM.fromURL(...) calls getGlobalDispatcher() from undici v7, which returns the v6 Agent
4. jsdom creates a JSDOMDispatcher wrapping this v6 Agent as its baseDispatcher
5. When jsdom makes an HTTP request, it wraps handlers using v7's WrapHandler class, then calls baseDispatcher.dispatch(opts, v7Handler) on the v6 Agent
6. The v6 Agent rejects the v7 handler: InvalidArgumentError: invalid onError method

Possible fixes:

• On the Undici side
  • Go back in time and bump the global dispatcher version in Undici v7.0.0.
  • Bump the global dispatcher version in a point release of Undici v7, and have jsdom upgraded to depend on that.
  • Make WrapHandler from Undici v7 compatible with Undici v6 Agents.
• On the jsdom side

  • Say that this is jsdom's fault for using the non-public WrapHandler API. Have jsdom write and bundle its own version of WrapHandler that works with both v6 and v7 Agents.

  • Stop using getGlobalDispatcher() as the default base dispatcher, and always use a new Undici v7 Agent as the default instead.

    • Downside: if the user has configured the global dispatcher (e.g. with proxy settings), jsdom won't pick them up.
      • Not sure how serious of a downside this is, given that it's not easy to set the global dispatcher. See discussions in Expose Undici's ProxyAgent and setGlobalDispatcher within Node node#43187 and https://nodejs.org/api/globals.html#custom-dispatcher .

  • Do some kind of conditional workaround like

    function getDefaultDispatcher() {
      const global = getGlobalDispatcher();
      if (global instanceof Dispatcher) {
        return global; // Created by the same copy of undici — compatible
      }
      return new Agent(); // Created by a different copy (e.g. Node's built-in v6) — incompatible
    }

    which will try to magically do the right thing. I'm not a fan though as it causes behavior to vary based on global state in a very hard to understand way.

It's also possible that after #4785 is merged, jsdom can stop using WrapHandler, and this problem will go away? (#4787 is already merged.)

Thoughts welcome.

[KarlGe]

Right!

* Bump the global dispatcher version in a point release of Undici v7, and have jsdom upgraded to depend on that.
* Make WrapHandler from Undici v7 compatible with Undici v6 Agents.

These seem reasonable to me, especially the global symbol, since it would let potential other projects that depend on Undici outside Node continue to work as well.

[mcollina]

@domenic can you create a reproduction for what jsdom is using?

undici v7 was theoretically designed to avoid this kind of problem, but it seems we have missed a case.

[domenic]

It's basically because jsdom is using the new-style handler interface which v6 does not support.

// Requires: Node <= 24 (ships built-in undici v6) + npm undici v7 installed.

// Step 1: Node's built-in fetch() causes a v6 Agent to be set as the global dispatcher.
await fetch("https://example.com");

// Step 2: npm undici v7 shares the same Symbol.for('undici.globalDispatcher.1'),
// so getGlobalDispatcher() returns the v6 Agent.
const { getGlobalDispatcher } = await import("undici");
const dispatcher = getGlobalDispatcher();

// Step 3: Dispatching with v7 new-style handlers fails. In jsdom's case,
// v7's WrapHandler.wrap() normalizes incoming handlers to new-style, but v6's
// assertRequestHandler requires old-style methods (onConnect, onError, etc.).
try {
  dispatcher.dispatch(
    { origin: "https://example.com", path: "/", method: "GET", headers: {} },
    {
      onRequestStart() {},
      onResponseStart() {},
      onResponseData() {},
      onResponseEnd() {},
      onResponseError() {}
    }
  );
} catch (err) {
  console.error(err.message);
}

[mcollina]

Yes, this is expected. You need to wrap your interceptor in

undici/lib/handler/wrap-handler.js

Line 5 in 0ce57ba

module.exports = class WrapHandler {

or analog.

(Probably not one of our best designs).

This is what I do somewhere else: https://github.com/platformatic/undici-thread-interceptor/blob/main/lib/wrap-handler.js.

[domenic]

It's a bit frustrating, since

1. WrapHandler is not a public API.
2. This is not documented; according to https://undici.nodejs.org/#/docs/api/Dispatcher?id=dispatcherdispatchoptions-handler my above code should work fine.

But, I guess we can just work around this for now (jsdom/jsdom#4056 is one attempt) and in Undici vNext this will get less messy.