denoland/deno · error · Error

Unknown built-in module

Error message

Unknown built-in module

What it means

Thrown by the CJS shim in ext/node/polyfills/01_require.js:1557 when require() targets a built-in module id ("node:..." or bare builtin) that loadNativeModule cannot resolve — i.e. Deno has no polyfill or native implementation for that builtin. The source even carries a TODO to convert it into Node's proper ERR_UNKNOWN_BUILTIN_MODULE error code, so today it surfaces as a plain Error with no code property.

Source

Thrown at ext/node/polyfills/01_require.js:1557

      if (result.format === "builtin") {
        const module = loadNativeModule(id, id);
        if (module) {
          return module.exports;
        }
        const mod = new Module(builtinFilename, parent);
        mod.exports = {};
        mod.loaded = true;
        Module._cache[builtinFilename] = mod;
        return mod.exports;
      }
    }

    maybeEmitNativeModuleDeprecation(id);
    const module = loadNativeModule(id, id);
    if (!module) {
      // TODO:
      // throw new ERR_UNKNOWN_BUILTIN_MODULE(filename);
      throw new Error("Unknown built-in module");
    }

    return module.exports;
  }

  if (cachedModule !== undefined) {
    updateChildren(parent, cachedModule, true);
    if (!cachedModule.loaded) {
      return getExportsForCircularRequire(cachedModule);
    }
    return cachedModule.exports;
  }

  // A resolve hook that redirected `require('zlib')` to a file path must
  // not silently fall back to the native module via the original request.
  if (!SetPrototypeHas(cjsHookResolvedFilenames, filename)) {
    maybeEmitNativeModuleDeprecation(filename);
    const mod = loadNativeModule(filename, request);

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Check the exact module name in the stack for typos (node:fs vs node:fss, node:test vs node:tes)
2. Run `deno info` on the failing module to confirm which file issued the require and whether a polyfill exists for that builtin in your Deno version
3. If the builtin genuinely lacks support, replace that dependency with a Deno/Web-API equivalent (e.g. node:sqlite -> Deno.KV or a WASM sqlite)
4. Wrap the require in try/catch with a fallback implementation for runtimes that lack the builtin

Example fix

// before
const { connect } = require("node:netc"); // unsupported/typo'd builtin -> "Unknown built-in module"

// after
const { connect } = require("node:net");

import { isBuiltin } from "node:module";
function safeRequireBuiltin(id) {
  if (!isBuiltin(id)) throw new Error(`not a builtin: ${id}`);
  return require(id);
}

const SUPPORTED = new Set(["fs", "path", "os", "util", "events", "stream", "net", "http", "https", "url", "crypto", "buffer", "child_process", "readline", "string_decoder", "timers", "zlib", "assert", "process", "tty", "querystring", "punycode", "perf_hooks", "v8", "vm", "worker_threads", "module", "constants", "sys", "diagnostics_channel", "async_hooks", "http2", "dgram", "dns", "cluster", "inspector", "trace_events", "wasi", "console", "test", "sqlite"]);
function isLikelySupportedBuiltin(id: string): boolean {
  return SUPPORTED.has(id.replace(/^node:/, ""));
}

try {
  mod = require("node:sqlite");
} catch (e) {
  if (e instanceof Error && /Unknown built-in module/.test(e.message)) {
    mod = await import("jsr:@db/sqlite"); // fallback
  } else throw e;
}

When it happens

Trigger: require("node:<name>") where <name> is a builtin Deno does not implement (or a typo like require("node:fss")); an npm dependency whose deep dependency does require("node:something-unsupported") under byonm/npm resolution.

Common situations: Running CLI-oriented or native-binding packages (esbuild-style wrappers, node:sqlite in older runtimes, node:test runner harnesses) under Deno; typo'd builtin names; code paths only reached in CI after an npm dependency upgrade pulled in a new native require.

Related errors

• Unsupported 'alpnProtocols' option provided. 'h2' and 'http/
• Socket is already destroyed - cannot upgrade to WebSocket
• Socket has no handle - cannot upgrade
• Socket is not a TCP socket - only TCP connections can be upg
• resolve hook must return { shortCircuit: true } or call next

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/be58eb55b1ae84f2. Report an issue: GitHub.