René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEA: embedder main cannot dynamically import non-builtin modules on Node 25.5+","articleBody":"### Version\nv25.9.0 (also reproduces on v25.7.0, v25.8.x). Does **not** reproduce on v24.x.\n\n### Platform\nLinux 6.17.0-19-generic x86_64\n\n### Subsystem\nsea, esm, embedding\n\n### What steps will reproduce the bug?\n\nMinimal repro, no external tools beyond `postject`:\n\n```bash\nmkdir -p /tmp/sea-repro \u0026\u0026 cd /tmp/sea-repro\n\ncat \u003e user.mjs \u003c\u003c'JS'\nconsole.log('hello from user module');\nJS\n\ncat \u003e bootstrap.js \u003c\u003c'JS'\nimport('file:///tmp/sea-repro/user.mjs').catch(err =\u003e {\n  console.error(err);\n  process.exit(1);\n});\nJS\n\ncat \u003e sea-config.json \u003c\u003c'JSON'\n{\n  \"main\": \"bootstrap.js\",\n  \"output\": \"sea-prep.blob\",\n  \"disableExperimentalSEAWarning\": true\n}\nJSON\n\nnode --experimental-sea-config sea-config.json\ncp \"$(command -v node)\" ./app\nnpx postject ./app NODE_SEA_BLOB sea-prep.blob \\\n  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2\n./app\n```\n\nSame failure occurs when:\n- `mainFormat` is set to `\"module\"` and the bootstrap uses `await import('file:///...')`\n- a CJS bootstrap calls `require('/abs/path.js')` on a non-builtin path\n\n### How often does it reproduce? Is there a required condition?\n\n100% on Node 25.5+. The identical repro prints `hello from user module` on Node 24.14.0, so this is a regression introduced somewhere in the 25.5+ window (around the `--build-sea` landing in #61167 and the `mainFormat: \"module\"` support in #61813).\n\n### What is the expected behavior?\n\nDynamic `import()` (and `require()` of absolute paths) from the SEA main should resolve through the normal module loader. This is how SEA worked from v20 through v24 and is what enables the common pattern of a small bootstrap baked into the SEA that stages setup (VFS overlays, monkey-patches, diagnostics, ...) and then hands control off to a real user entrypoint on disk.\n\n### What do you see instead?\n\n```\nError [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: file:///tmp/sea-repro/user.mjs\n    at loadBuiltinModuleForEmbedder (node:internal/modules/helpers:165:9)\n    at getBuiltinModuleWrapForEmbedder (node:internal/modules/esm/utils:237:10)\n    at importModuleDynamicallyForEmbedder (node:internal/modules/esm/utils:250:10)\n    at importModuleDynamicallyCallback (node:internal/modules/esm/utils:282:12)\n    at bootstrap.js:1:1\n    at embedderRunCjs (node:internal/main/embedding:93:10)\n    at embedderRunEntryPoint (node:internal/main/embedding:128:12) {\n  code: 'ERR_UNKNOWN_BUILTIN_MODULE'\n}\n```\n\n### Root cause\n\nFrom `lib/internal/modules/esm/utils.js` in v25.9.0:\n\n```js\n// For embedder entry point ESM, only allow built-in modules.\nif (referrerSymbol === embedder_module_hdo) {\n  return importModuleDynamicallyForEmbedder(specifier, phase, attributes, referrerName);\n}\n```\n\n```js\nfunction importModuleDynamicallyForEmbedder(specifier, phase, attributes, referrerName) {\n  // Ignore phase and attributes for embedder ESM for now, because this only supports loading builtins.\n  return getBuiltinModuleWrapForEmbedder(specifier).getNamespace();\n}\n```\n\nThe CJS path has the same limitation: `embedderRequire` in `lib/internal/main/embedding.js` routes through `loadBuiltinModuleForEmbedder`, so `require('/abs/path')` from a CJS SEA main on Node 25.5+ also throws `ERR_UNKNOWN_BUILTIN_MODULE`.\n\nThis means the SEA main — whether `mainFormat: \"commonjs\"` or `mainFormat: \"module\"` — can only load builtin modules via its own `require`/`import()`, and cannot hand off to a user script.\n\n### Additional information\n\n**Workaround** (for anyone hitting this in the wild): obtain `Module` via `require('module')` (which succeeds because `module` is a builtin), set `process.argv[1]` to the real entrypoint, then call `Module.runMain()`. `Module.runMain` uses the real CJS loader and, on Node 22.12+, transparently handles ESM entries via `require(esm)`. Caveat: user entrypoints that use top-level `await` cannot go through this path — `require(esm)` rejects them — so there is currently **no** way to load a TLA-using ESM user entrypoint from an SEA main on Node 25.5+.\n\n**Request**: route `importModuleDynamicallyForEmbedder` and `embedderRequire` through the default loaders (the same path `source_text_module_default_hdo` / `vm_dynamic_import_default_internal` use), so embedders — including SEA — can keep using dynamic `import()` / `require()` to hand off to a user entrypoint after setup.\n\nContext: I'm the maintainer of [yao-pkg/pkg](https://github.com/yao-pkg/pkg) (the maintained fork of vercel/pkg); pkg's enhanced SEA mode builds a small bootstrap that mounts a VFS and then hands off to the user entrypoint, which is exactly the pattern this regression breaks.","author":{"url":"https://github.com/robertsLando","@type":"Person","name":"robertsLando"},"datePublished":"2026-04-14T08:53:31.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":4},"url":"https://github.com/62726/node/issues/62726"}