{"record":{"id":"8a3b6ef20e34f6ca","repo":"oven-sh/bun","slug":"builtin-bundler-specifier-cannot-be-imported","errorCode":null,"errorMessage":"Builtin Bundler: \"${specifier}\" cannot be imported from \"${from}\" because it doesn't get a module ID. ${suffix}","messagePattern":"Builtin Bundler: \"(.+?)\" cannot be imported from \"(.+?)\" because it doesn't get a module ID\\. (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/codegen/internal-module-registry-scanner.ts","lineNumber":78,"sourceCode":"\n  function codegenRequireId(id: string) {\n    return `(__intrinsic__getInternalField(__intrinsic__internalModuleRegistry, ${id}) || __intrinsic__createInternalModuleById(${id}))`;\n  }\n\n  const requireTransformer = (specifier: string, from: string) => {\n    const directMatch = internalRegistry.get(specifier);\n    if (directMatch) return codegenRequireId(`${directMatch}/*${specifier}*/`);\n\n    const relativeMatch =\n      resolveSyncOrNull(specifier, path.join(basedir, path.dirname(from))) ?? resolveSyncOrNull(specifier, basedir);\n\n    const suffix =\n      'Only files in \"src/js\" besides \"src/js/builtins\" can be imported here. Note that the \"node:\" or \"bun:\" prefix is required here.';\n\n    if (relativeMatch) {\n      const found = moduleList.indexOf(path.relative(basedir, relativeMatch).replaceAll(\"\\\\\", \"/\"));\n      if (found === -1) {\n        throw new Error(\n          `Builtin Bundler: \"${specifier}\" cannot be imported from \"${from}\" because it doesn't get a module ID. ${suffix}`,\n        );\n      }\n      return codegenRequireId(`${found}/*${path.relative(basedir, relativeMatch)}*/`);\n    }\n\n    throw new Error(`Builtin Bundler: Could not resolve \"${specifier}\" in \"${from}\". ${suffix}`);\n  };\n\n  return {\n    requireTransformer,\n    nativeModuleIds,\n    nativeModuleEnums,\n    nativeModuleEnumToId,\n    internalRegistry,\n    moduleList,\n    nativeStartIndex,\n  } as const;","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/oven-sh/bun/blob/8c5296ac459e8252d3cd702f3fbcbb0c249d95d5/src/codegen/internal-module-registry-scanner.ts#L60-L96","documentation":"While bundling Bun's builtin JS (src/js), every import must map to an internal module ID. The scanner resolves the specifier to a file and looks it up in the module list; a file that exists but was never given an ID — anything under src/js/builtins, or files outside the scanned node/, bun/, thirdparty/, internal/ directories — cannot be imported this way.","triggerScenarios":"Importing a file from src/js/builtins via a relative path, or importing a newly added src/js file that lives outside the four scanned directories, from any builtin module.","commonSituations":"Reusing builtin-only code from a node/ or bun/ module; adding a new top-level folder under src/js and importing from it; moving a helper into builtins and forgetting to update importers.","solutions":["Import the module by its canonical specifier with the required prefix: `node:...` or `bun:...`.","Move shared code out of src/js/builtins into one of the scanned dirs (src/js/node, src/js/bun, src/js/thirdparty, src/js/internal).","If importing a native (C++) module, use its node:/bun: name so it resolves through the native module registry instead of the filesystem."],"exampleFix":"// before (inside src/js/node/foo.ts)\nimport { x } from \"../builtins/commonjs/helpers\";\n\n// after\nimport { x } from \"bun:internal-for-testing\"; // or move helpers into src/js/internal/ and import via internal path","handlingStrategy":"validation","validationCode":"import { resolveSyncOrNull } from \"./helpers\";\nfunction assertBuiltinImportAllowed(specifier: string, from: string, registry: Map<string, number>, moduleList: string[], basedir: string) {\n  if (registry.has(specifier)) return;\n  const resolved = resolveSyncOrNull(specifier, path.join(basedir, path.dirname(from)));\n  if (!resolved) return; // resolution failure is a different error\n  const rel = path.relative(basedir, resolved).replaceAll(\"\\\\\", \"/\");\n  if (moduleList.indexOf(rel) === -1) {\n    throw new Error(`${from}: import of ${specifier} (${rel}) gets no module ID; use node:/bun: or move it under src/js`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In builtin code, always import native modules via node:/bun: specifiers.","Place any shared builtin under src/js/{node,bun,thirdparty,internal} — never import from src/js/builtins.","When moving files under src/js, grep importers and update specifiers in the same change."],"tags":["codegen","builtin-bundler","module-registry","imports"],"backgroundTag":null,"analyzedSha":"8c5296ac459e8252d3cd702f3fbcbb0c249d95d5","analyzedAt":"2026-08-16T08:01:58.794Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}