OpenTelemetry ESM instrumentation crashes: load hook returns null source for builtin format

[colinhacks]

Running an OpenTelemetry-instrumented ESM app under Nub crashes at startup. Plain Node with the same loader works.

Repro

npm init -y && npm pkg set type=module
npm i ms @opentelemetry/instrumentation
printf 'import ms from "ms";\nconsole.log("APP_OK");\n' > app.mjs
L=node_modules/@opentelemetry/instrumentation/hook.mjs

node --experimental-loader=$L app.mjs                 # exit 0, APP_OK
nub app.mjs                                           # exit 0, APP_OK
NODE_OPTIONS="--experimental-loader=$L" nub app.mjs   # exit 1

TypeError [ERR_INVALID_RETURN_PROPERTY_VALUE]: Expected a string, an ArrayBuffer, or a TypedArray to be returned for the "source" from the "load" hook but got null.
    at validateSourceStrict (node:internal/modules/customization_hooks:293:11)
    at validateLoadSloppy (node:internal/modules/customization_hooks:278:3)
    at #loadSync (node:internal/modules/esm/loader:832:16)

Nub 0.6.0, Node 26.5.0, macOS arm64.

Cause

The recovery path at runtime/preload-common.cjs:649-672 handles the loadSync stub Node throws when a user async module.register loader is present — which is what OpenTelemetry's ESM hook is. Its builtin branch returns:

return { format: "builtin", source: null, shortCircuit: true };

Node's validateSourceStrict accepts a null source only when format === "commonjs". Line 541 does that legally; the builtin branch does not, so the recovery path itself throws.

Ruled out

• The version band in nodeHookComposeBroken() (22.15.0–24.11.0) leaves sync hooks installed on Node 26 rather than downgrading. Not the cause: a plain-Node sync registerHooks pass-through composed with the same OpenTelemetry async loader on Node 26.5.0 exits 0.
• Setting __NUB_FORCE_ASYNC_TIER=1 is not a workaround, and cannot be tested that way — Nub strips the variable before the child sees it, so the child reads undefined. It is launcher-set only, via force_async_tier_env in spawn.rs. Crash traces with and without it are byte-identical.

Impact

Any ESM project using OpenTelemetry auto-instrumentation. The ESM hook is the only supported way to instrument ESM imports — the --require/--import register entrypoint alone registers no ESM loader — so this is the standard path, not an exotic configuration. No known workaround.

[pullfrog]

Reproduced, but the cause is a different code path than the one in the report.

Repro environment: nub 0.6.0 (published), Node 24.18.0, Linux x64 — no macOS runner available here. Same error, same validator frames (customization_hooks:293). Node 24.18.0 sits above the nodeHookComposeBroken() ceiling (24.11.0), so the fast tier stays and the conditions match Node 26.

Not the builtin branch

Instrumented the extracted 0.6.0 runtime (/tmp/nub-*/runtime-0.6.0-*/preload-common.cjs) with a log at the format: "builtin" recovery return, at the loadViaDisk commonjs return, and at the isAsyncLoaderSyncStub catch. None of the three fired on the crashing run.

That branch also cannot produce this error for a node: URL. validateSourceStrict exempts anything starting with node: before it checks source, in both 24.18.0 and v26.5.0:

if (!StringPrototypeStartsWith(url, 'node:') &&
  typeof result.source !== 'string' && …) { throw new ERR_INVALID_RETURN_PROPERTY_VALUE(…) }

Actual cause: the commonjs → commonjs-sync relabel

Logging every return of nub's load hook gives the crashing pair:

nextLoad -> file:///tmp/otel/node_modules/import-in-the-middle/lib/register.js fmt= commonjs      src= null
load RET    file:///tmp/otel/node_modules/import-in-the-middle/lib/register.js fmt= commonjs-sync src= null

The default step returns { format: "commonjs", source: null } — the async-loader defaultLoad quirk — and the #18 relabel (preload-common.cjs:707-715) rewrites the format to commonjs-sync while keeping source: null. validateSourcePermissive exempts a null source only for format === "commonjs", so commonjs-sync falls through to the strict check and throws. The module is import-in-the-middle/lib/register.js, pulled in by OpenTelemetry's ESM hook.

The relabel's own guard is supposed to prevent this — it skips whenever a user async loader is active — but both detection channels miss a NODE_OPTIONS-delivered loader:

• cliAsyncLoaderPresent() reads only process.execArgv, and NODE_OPTIONS entries are not hoisted there. Confirmed on this run: execArgv held nub's own injected flags but neither the user's --experimental-loader nor nub's own --require.
• --experimental-loader registers natively and never calls module.register() in the main thread, so __userAsyncLoaderRegistered stays false.

foreignAsyncLoaderFlagPresent() (the tier-downgrade sibling, line 261) already scans both channels. Teaching cliAsyncLoaderPresent() the same NODE_OPTIONS scan fixes the repro: patched into the extracted runtime, the crashing command prints APP_OK, and a bare nub app.mjs is unchanged. The detector functions and the relabel block are byte-identical between the 0.6.0 tag and main, so main still has it.

Band and workaround

Node 22.23.1 (inside the broken-compose band) exits 0 — nub auto-downgrades to the async tier there, and that decision does read NODE_OPTIONS. The crash needs the fast tier plus a NODE_OPTIONS-delivered loader flag, i.e. Node 24.12+/25.2+/26.

The register() form does work today, so this is not unworkaroundable:

printf 'import { register } from "node:module";\nimport { pathToFileURL } from "node:url";\nregister("@opentelemetry/instrumentation/hook.mjs", pathToFileURL("./"));\n' > reg.mjs
NODE_OPTIONS="--import ./reg.mjs" nub app.mjs   # APP_OK

It registers the same import-in-the-middle loader, and it is the form Node's own --experimental-loader deprecation warning points at. --experimental-loader should still work, so this stays a bug.

One repro note: on Node 24 the loader path needs the ./ prefix. --experimental-loader=node_modules/… fails with Cannot find package 'node_modules' on plain Node too, unrelated to nub.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}