Webpack "UnhandledSchemeError ... node:" protocol import in CI

By Daniel Zoghalchali·Latchkey

A module imports a Node built-in using the node: URI scheme (for example node:fs). Webpack does not resolve that scheme out of the box, so it raises UnhandledSchemeError during the build.

What this error means

The build fails with "UnhandledSchemeError: Reading from 'node:fs' is not handled by plugins (Unhandled scheme)" and a note that Webpack supports data:, file: and http(s): by default.

Module build failed: UnhandledSchemeError: Reading from "node:buffer" is not
handled by plugins (Unhandled scheme).
Webpack supports "data:" and "file:" URIs by default.
You may need an additional plugin to handle "node:" URIs.

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

Common causes

A dependency uses node: prefixed imports

Newer packages import core modules as node:fs or node:buffer; older Webpack 5 minors do not resolve that scheme.

A browser target pulling in Node built-ins

Bundling Node-only code for the web surfaces the scheme because there is no browser equivalent to map it to.

How to fix it

Upgrade Webpack so it resolves node:

Recent Webpack 5 versions handle the node: scheme for server targets. Upgrade to a version that supports it.

npm install webpack@latest
npx webpack --version

Map node: imports with a NormalModuleReplacementPlugin

For a browser build, strip the prefix or point the import at a polyfill so Webpack can resolve it.

new webpack.NormalModuleReplacementPlugin(
  /^node:/,
  (resource) => { resource.request = resource.request.replace(/^node:/, ''); }
)

Make the build reproducible before you debug it

• Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
• Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
• Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
• Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

How to prevent it

• Keep Webpack current so new URI schemes are supported.
• Target the right platform so Node built-ins are not bundled for the browser.
• Audit dependencies that switched to node: prefixed imports.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation