How to Fix "Module Not Found" Errors When Migrating from Node.js to Bun

Bun advertises strong Node.js compatibility, and for the majority of packages, that holds up well — but 'mostly compatible' means migration projects still hit a specific, recurring set of module resolution errors worth knowing about ahead of time rather than debugging blind.

The most common cause is a package relying on Node.js built-in modules that Bun hasn't fully implemented, or implements with subtly different behavior. Bun's built-in module support has expanded significantly over time, but less common built-ins or edge-case APIs within otherwise-supported modules can still be missing, producing a module-not-found or method-not-a-function error that looks like a resolution problem but is actually an implementation gap.

Native Node addons (packages with a .node binary component, common in things like certain database drivers or image processing libraries) are a frequent source of migration friction, since these are compiled specifically for Node's native module system. Bun has been adding compatibility here too, but a package with a native addon is worth checking against Bun's compatibility notes specifically before assuming it will just work.

Package.json 'exports' field resolution is another subtle source of mismatches. Modern packages increasingly use conditional exports to serve different code for different runtimes and module systems (CommonJS versus ESM, Node versus browser). If a package's exports configuration doesn't explicitly account for Bun as a target, Bun generally falls back to Node-compatible resolution — which usually works, but occasionally a package's specific conditional logic produces a different result than expected, leading to importing the wrong file or a genuinely missing one.

The practical debugging approach: when a module-not-found error appears, first check whether it's a Node built-in (search Bun's documentation for that specific module's support status) or a third-party package with native bindings (check the package's own compatibility notes or open issues for Bun-specific reports, since you're very unlikely to be the first person to hit a given package's incompatibility).

For packages that genuinely aren't Bun-compatible yet, the two practical paths are finding an actively maintained alternative package that is compatible, or running just that specific dependency's usage under Node via a compatibility shim while the rest of the application runs on Bun — a reasonable interim step during a gradual migration rather than an all-or-nothing switch.

Bun's own compatibility table and changelog are worth checking directly before assuming a gap is permanent — this is an actively developed area, and specific built-ins or native-addon categories that were unsupported at one point are frequently added in subsequent releases, so a failure today doesn't necessarily mean the same failure persists after an update.