René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"24.19.0: --experimental-import-text breaks loader hooks that own with { type: 'text' }","articleBody":"### Version\n\n24.19.0\n\n### Platform\n\n```text\nVersion: v24.19.0 (works on v24.18.0)\nPlatform: Darwin 24.6.0 arm64 (macOS 15.7), official nvm binaries; originally hit in node:24-alpine on ECS Fargate\nSubsystem: esm, module\n```\n\n### Subsystem\n\nloader\n\n### What steps will reproduce the bug?\n\nThree files:\n\n`asset.txt`\n```\nhello from a text asset\n```\n\n`register-hooks.mjs`\n```js\nimport { registerHooks } from 'node:module';\n\nregisterHooks({\n\tload(url, context, nextLoad) {\n\t\tif (context.importAttributes?.type === 'text') {\n\t\t\t// Use nextLoad purely as a source reader, with a format hint Node does not\n\t\t\t// implement, then return the real module ourselves.\n\t\t\tconst { source } = nextLoad(url, { ...context, format: 'text' });\n\t\t\treturn {\n\t\t\t\tformat: 'module',\n\t\t\t\tsource: `export default ${JSON.stringify(source.toString())}`,\n\t\t\t};\n\t\t}\n\t\treturn nextLoad(url, context);\n\t},\n});\n```\n\n`main.mjs`\n```js\nimport text from './asset.txt' with { type: 'text' };\nconsole.log('loaded via hook:', JSON.stringify(text));\n```\n\nRun:\n```console\n$ node --import ./register-hooks.mjs ./main.mjs\n```\n\nv24.18.0 — works:\n```\nloaded via hook: \"hello from a text asset\\n\"\n```\n\nv24.19.0 — throws `ERR_IMPORT_ATTRIBUTE_UNSUPPORTED` (full output in \"What do you see instead\").\n\nThe same repro written against the deprecated `module.register()` API fails the same way, only through `defaultLoad` instead of `defaultLoadSync`.\n\nSame file tree, no flags, no other changes. `git bisect` isn't needed: the change is https://github.com/nodejs/node/commit/3c1636dabf (#62300, SEMVER-MINOR, first released in v24.19.0). Adding `--experimental-import-text` on v24.19.0 makes the repro pass again on both APIs.\n\n### How often does it reproduce? Is there a required condition?\n\n100% deterministic on v24.19.0 and later (not timing-, load- or platform-dependent)\n\nRequired conditions, all four:\n1. A registered load hook — `module.registerHooks()` or the deprecated `module.register()`; both are affected.\n2. An import carrying `with { type: 'text' }`.\n3. The hook delegating to `nextLoad()` (e.g. to read the file's bytes before transforming it) rather than short-circuiting with its own source. Validation lives in `defaultLoad`/`defaultLoadSync`, at the bottom of the hook chain, so only delegating hooks are hit.\n4. `--experimental-import-text` not set.\n\nIndependent of file extension, of the `format` hint passed to `nextLoad()`, and of whether the hooks are synchronous or asynchronous. Unaffected: hooks that use any other attribute value (`with { type: 'buffer' }` etc.) still take the \"unrecognized type\" path and still work, only the value Node claimed in this PR broke.\n\n### What is the expected behavior? Why is that the expected behavior?\n\nWith `--experimental-import-text` absent, v24.19.0 should behave exactly as v24.18.0 did: `type: 'text'` should reach the `case undefined: break` branch in `validateAttributes`, whose own comment states the intent (\"Ignore attributes for module formats we don't recognize, to allow new formats to be added in the future.\") The attribute should be left for loader hooks to interpret.\n\nThree reasons:\n\n1. A SEMVER-MINOR feature behind an experimental flag should be inert when the flag is off. #62300 is described as purely additive, but its flag-off path is a new hard throw on input that previously worked. If the feature is experimental, the rejection cannot be unconditional.\n2. That tolerance branch is the only mechanism loader hooks have for owning an attribute type. #51128 asked for a real one (a hook for custom attributes, or a way to disable built-in validation when hooks are registered) and was closed without providing it. Hooks were left with the ignore-unknown-types path and are now being broken for having used it.\n3. Reading source via `nextLoad()` is the documented way for a load hook to get a file's contents. The break specifically punishes hooks that follow that guidance; short-circuiting hooks that read the file themselves are unaffected.\n\n### What do you see instead?\n\n`registerHooks()` on v24.19.0:\n\n```\nnode:internal/modules/esm/assert:73\n    throw new ERR_IMPORT_ATTRIBUTE_UNSUPPORTED('type', importAttributes.type, url);\n          ^\n\nTypeError [ERR_IMPORT_ATTRIBUTE_UNSUPPORTED]: Import attribute \"type\" with value \"text\" is not supported in file:///private/tmp/repro-62300/asset.txt\n    at validateAttributes (node:internal/modules/esm/assert:73:11)\n    at defaultLoadSync (node:internal/modules/esm/load:163:3)\n    at #loadAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:802:12)\n    at nextStep (node:internal/modules/customization_hooks:189:26)\n    at load (file:///private/tmp/repro-62300/register-hooks.mjs:8:23)\n    at nextStep (node:internal/modules/customization_hooks:189:26)\n    at loadWithHooks (node:internal/modules/customization_hooks:374:18)\n    at #loadSync (node:internal/modules/esm/loader:825:16)\n    at ModuleLoader.load (node:internal/modules/esm/loader:783:26)\n    at ModuleLoader.loadAndTranslate (node:internal/modules/esm/loader:494:31) {\n  code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED'\n}\n\nNode.js v24.19.0\n```\n\nWith the deprecated `module.register()`, the same error arrives via `defaultLoad (node:internal/modules/esm/load:108:3)`.\n\nThe throw happens inside the hook's own `nextLoad()` call, so the hook never gets to return. The message names the asset URL and the attribute, but says nothing about the new flag or about the registered hooks, so from an application's point of view the import simply stops working after a patch-level base-image bump.\n\n### Additional information\n\nRoot cause, in `lib/internal/modules/esm/assert.js` as of #62300:\n\n- `formatTypeMap` gained `'text': 'text'`, so `validType` is no longer `undefined` for\n  the text format, and\n- a new unconditional check throws before the switch:\n\n  ```js\n  if (validType !== undefined &&\n    importAttributes.type === 'text' &&\n    !getOptionValue('--experimental-import-text')) {\n    throw new ERR_IMPORT_ATTRIBUTE_UNSUPPORTED('type', importAttributes.type, url);\n  }\n  ```\n\nSetting `--experimental-import-text` does make the repro pass, so the flag is a workaround — but it is the wrong requirement: an application has to opt into an experimental module feature it does not use, on every entrypoint (`node`, test runners, workers, tooling), purely to stop Node from rejecting an attribute its own loader handles. It is also unavailable on every release line that predates the flag, so there is no single spelling that runs on 24.18 and 24.19.\n\nReal-world impact: a service that loads ~33 email-template asset sets through `with { type: 'text' }` and a registered load hook went from healthy on 24.18 to crash-looping on the first template on 24.19, dying before any application code ran. Because the image is `node:24-alpine`, this arrived with a rebuild rather than a version bump, one day after 24.19.0 was released, and cost a production rollback. Mitigation was to pin the base image, then delete the import-attribute loaders entirely and read the assets with `fs` + `new URL(..., import.meta.url)` across 47 files.\n\nRequests:\n1. Make the flag-off path inert — when `--experimental-import-text` is not set, do not add `'text'` to the recognized-format map and do not throw; fall through to the unrecognized-attribute path so hooks keep working as on 24.18.\n2. Give hooks a supported way to claim attribute types (#51128) before Node claims further type names, otherwise each new built-in type is another silent break for whoever already used that name.\n3. Note the behaviour change for loader-hook consumers in the changelog, and add regression tests covering a registered load hook that handles `with { type: 'text' }` without the flag, for both `module.registerHooks()` (`defaultLoadSync`) and `module.register()` (`defaultLoad`). The PR's tests only cover flag-on and flag-off without hooks.","author":{"url":"https://github.com/richterdennis","@type":"Person","name":"richterdennis"},"datePublished":"2026-08-11T07:26:37Z","url":"https://github.com/nodejs/node/issues/65210"}