oven-sh/bun · error · Error

Builtin Bundler: "${specifier}" cannot be imported from "${f

Error message

Builtin Bundler: "${specifier}" cannot be imported from "${from}" because it doesn't get a module ID. ${suffix}

What it means

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.

Source

Thrown at src/codegen/internal-module-registry-scanner.ts:78

  function codegenRequireId(id: string) {
    return `(__intrinsic__getInternalField(__intrinsic__internalModuleRegistry, ${id}) || __intrinsic__createInternalModuleById(${id}))`;
  }

  const requireTransformer = (specifier: string, from: string) => {
    const directMatch = internalRegistry.get(specifier);
    if (directMatch) return codegenRequireId(`${directMatch}/*${specifier}*/`);

    const relativeMatch =
      resolveSyncOrNull(specifier, path.join(basedir, path.dirname(from))) ?? resolveSyncOrNull(specifier, basedir);

    const suffix =
      'Only files in "src/js" besides "src/js/builtins" can be imported here. Note that the "node:" or "bun:" prefix is required here.';

    if (relativeMatch) {
      const found = moduleList.indexOf(path.relative(basedir, relativeMatch).replaceAll("\\", "/"));
      if (found === -1) {
        throw new Error(
          `Builtin Bundler: "${specifier}" cannot be imported from "${from}" because it doesn't get a module ID. ${suffix}`,
        );
      }
      return codegenRequireId(`${found}/*${path.relative(basedir, relativeMatch)}*/`);
    }

    throw new Error(`Builtin Bundler: Could not resolve "${specifier}" in "${from}". ${suffix}`);
  };

  return {
    requireTransformer,
    nativeModuleIds,
    nativeModuleEnums,
    nativeModuleEnumToId,
    internalRegistry,
    moduleList,
    nativeStartIndex,
  } as const;

View on GitHub (pinned to 8c5296ac45)

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.

Example fix

// before (inside src/js/node/foo.ts)
import { x } from "../builtins/commonjs/helpers";

// after
import { x } from "bun:internal-for-testing"; // or move helpers into src/js/internal/ and import via internal path

Defensive patterns

Strategy: validation

Validate before calling

import { resolveSyncOrNull } from "./helpers";
function assertBuiltinImportAllowed(specifier: string, from: string, registry: Map<string, number>, moduleList: string[], basedir: string) {
  if (registry.has(specifier)) return;
  const resolved = resolveSyncOrNull(specifier, path.join(basedir, path.dirname(from)));
  if (!resolved) return; // resolution failure is a different error
  const rel = path.relative(basedir, resolved).replaceAll("\\", "/");
  if (moduleList.indexOf(rel) === -1) {
    throw new Error(`${from}: import of ${specifier} (${rel}) gets no module ID; use node:/bun: or move it under src/js`);
  }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/8a3b6ef20e34f6ca. Report an issue: GitHub.