Node 26+: UND_ERR_INVALID_ARG: invalid onError method on first request (Agent/fetch undici version mismatch)

[shaitourchin]

Summary

On Node 26.x (and presumably any future major that ships a stricter undici), the first request through @qdrant/js-client-rest fails with:

UND_ERR_INVALID_ARG: invalid onError method

The cause appears to be a version mismatch between two undicis in the same process:

• @qdrant/js-client-rest pins undici: ^6.23.0 and constructs an undici.Agent (in packages/js-client-rest/src/dispatcher.ts).
• It passes that Agent as the dispatcher option to Node's built-in fetch(), which on Node 26 uses a newer undici internally.
• The two undicis disagree on the dispatcher hook contract — the newer one validates onError strictly and rejects the v6 Agent's shape on first dispatch.

The client itself has no onError in source (I grepped dist/); the error originates inside undici's internal validation pipeline when fetch tries to use the externally-constructed Agent.

Environment

@qdrant/js-client-rest	1.18.0 (latest as of filing); declared ^1.17.0 by downstream
Node (broken)	26.0.0
Node (works)	22.x
OS	macOS 14 (also reported on Linux x86_64 per downstream notes)
Qdrant server	v1.17.0

Reproduction (constructed; not directly executed)

I encountered this through socraticode — an MCP server that wraps the qdrant client — not by running the minimal script below. The script is reconstructed from inspecting dispatcher.ts and should exercise the same failing code path. If a maintainer can confirm or refute the minimal repro, that'll tell us whether the failure is purely in the dispatcher path or whether it also requires socraticode-specific usage.

# Start a Qdrant instance (any 1.x image)
docker run --rm -d -p 6333:6333 --name qdrant-repro qdrant/qdrant:v1.17.0

# Minimal client repro
mkdir qdrant-undici-repro && cd qdrant-undici-repro
npm init -y >/dev/null
npm pkg set type=module >/dev/null
npm install @qdrant/js-client-rest@1.18.0 >/dev/null

cat > repro.mjs <<'EOF'
import { QdrantClient } from '@qdrant/js-client-rest';
const client = new QdrantClient({ url: 'http://localhost:6333' });
console.log(await client.getCollections());
EOF

node --version
node repro.mjs

Expected (observed on Node 22.x)

v22.x.x
{ collections: [] }

Actual (Node 26.0.0)

v26.0.0
node:internal/deps/undici/undici:...
    throw new InvalidArgumentError('invalid onError method')
    ^
TypeError [UND_ERR_INVALID_ARG]: invalid onError method
    at ...

Root cause (best guess)

packages/js-client-rest/src/dispatcher.ts does:

import { Agent } from 'undici';
export const createDispatcher = (connections = 25) =>
  new Agent({ /* ... */ });

When this Agent (from the npm-installed undici@^6) is passed to Node's built-in fetch(), fetch routes the dispatch through Node's bundled undici. The bundled undici has tightened its dispatcher-hook validation between Node 22's vendored version and Node 26's — it now requires the request handler's onError to be a function with a specific signature, and the v6 Agent doesn't satisfy it.

This is structurally a "two undicis in one process" problem. As long as the client constructs its dispatcher with one undici version and fetch handles it with another, contract drift between them will keep surfacing as cryptic errors.

Suggested fixes (already in flight)

Two existing open PRs in this repo would likely both fix this:

• undici major upgrade #123 — undici major upgrade. If the client moves to undici 7 (or whatever Node 26 ships), both sides agree on the contract.
• Inject fetch into REST transport #128 — Inject fetch into REST transport. If callers can supply their own fetch (e.g. from the same undici package the client uses), there's no two-undici problem at all.

I'd defer to maintainer judgment on which to prioritize, but #128 in particular sidesteps the entire class of bug — every future undici contract drift becomes a non-issue because the user controls both sides.

If neither lands soon, a minimal interim mitigation might be to import undici.fetch and undici.Agent from the same module (import { Agent, fetch } from 'undici') and use both, instead of mixing the npm Agent with Node's global fetch. That keeps the two sides on the same undici version regardless of the Node version.

Downstream impact

This bug affects any tool built on @qdrant/js-client-rest that runs under Node 26+. In our case it's socraticode (an MCP server that wraps a Qdrant-backed codebase index). I'm filing a separate PR there that refuses Node 26+ with a clear error message until this is resolved upstream — but it'd be much better to fix the root cause.

Happy to test a candidate fix on Node 26.x against a real workload.

[FunctionPoint]

Just started trying qdrant. I have this error too.
Cannot downgrade to earlier Node.js version due to other dependencies.
Please fix asap. For now I'll have to use to another vector store...

[gregoryfoster]

Confirming the repro executes (no socraticode), plus a version matrix that bears on the fix choice

I hit this via socraticode too, but I ran your minimal script verbatim (just repointed at a local Qdrant) against a real server — so this is the plain client path, not socraticode-specific. It reproduces exactly:

Node	built-in undici (process.versions.undici)	standalone undici (qdrant Agent)	getCollections()
22.18.0	6.21.2	6.27.0	✅ { collections: [...] }
26.4.0	8.5.0	6.27.0	❌ UND_ERR_INVALID_ARG: invalid onError method

So the mechanism is precisely as you diagnosed: it works when the client's Agent major matches Node's built-in-fetch undici major (both 6 on Node 22), and breaks across the 6↔8 boundary on Node 26.

Where it gets decisive for the fix: I tested pinning the standalone undici (via npm overrides) to each major and ran the same repro on both Node lines:

standalone undici override	Node 22.18.0 (built-in undici 6)	Node 26.4.0 (built-in undici 8)
6.27.0	✅ OK	❌ invalid onError method
7.16.0 / 7.10.0	✅ OK	❌ Result came uninitialized
8.5.0 (matches Node 26)	❌ invalid onRequestStart method	✅ OK

The skew is symmetric: the only standalone-undici major that works is the one matching the runtime Node's built-in undici. Two consequences:

1. A static undici bump (undici major upgrade #123) can't fix all supported Node versions at once. Moving to undici 7 doesn't fix Node 26 (fails differently); moving to undici 8 fixes Node 26 but breaks Node ≤24 (built-in undici 6). Any single pin just relocates the breakage.
2. Inject fetch into REST transport #128 (inject/own the fetch) is the robust fix — it's the only approach that removes the cross-version handoff entirely, because the Agent and the fetch that consumes it then come from the same undici. Your interim suggestion (import { Agent, fetch } from 'undici' and use both) has the same property and would unblock Node 26+ immediately regardless of what undici Node bundles.

Happy to test a candidate build (either PR) on Node 26.4.0 against a real workload.

[bot-dodi]

Downstream data point supporting "make the per-request dispatcher optional/removable" (complements the matrix above, which we independently reproduced on Node 22.22 / 24.13 / 26.5 with identical results):

We ship this client inside @keepur/hive and fixed the Node 26 breakage by stubbing dispatcher.js out entirely at bundle time (esbuild plugin returns createDispatcher = () => undefined), so all client calls ride the runtime's plain built-in fetch(). This has been validated against a production Qdrant workload (memory/semantic-search pipelines) across Node 22/24/26 — no dispatcher-class failures, and connection pooling is preserved via a global dispatcher instead of the per-request one (keepur/hive#321).

One nuance worth knowing when weighing the fix options: the cross-major incompatibility is specific to the per-request dispatcher handoff. The global dispatcher path is cross-major-safe from undici v8's side by design — v8's setGlobalDispatcher writes both Symbol.for("undici.globalDispatcher.2") (raw, read by Node 26+ internals) and .1 (wrapped in Dispatcher1Wrapper for older internals). So consumers who need pooling/tuning can setGlobalDispatcher an undici@8 Agent and it works on Node 22/24/26 — which means dropping (or making optional) the per-request Agent doesn't have to cost anyone connection pooling.

That makes two viable shapes from our testing: (a) same-undici pairing (import { fetch, Agent } from "undici") as proposed in #128 — robust, keeps per-request tuning; or (b) on Node, skip the custom dispatcher by default and let built-in fetch + an optional user-supplied global dispatcher handle pooling. Either ends the cross-version handoff; a plain undici dep bump alone cannot, as the matrix above shows.

[ManjeetSingh-02]

Environment

Node: 26.6.0
Works on: Node 22.x, Node 24.x
Fails on: Node 26.6.0

@qdrant/js-client-rest: 1.18.0
Qdrant server: localhost:6333

Code

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({
  url: "http://localhost:6333",
});

console.log(await client.getCollections());

on line 66 of node_modules/@qdrant/js-client-rest/dist/esm/api-client.js, instead of

dispatcher: typeof process !== 'undefined' &&
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
    process.versions?.node
    ? createDispatcher(connections)
    : undefined,

i used - dispatcher: undefined,
and it worked, the cause i determined is that
the handler requires a function named as onError
but in node 26, the function present is onResponseError

[IvanPleshkov]

Fixed in v1.19