Node.js ERR_MODULE_NOT_FOUND after a build: check the emitted import path

Identify what Node is trying to resolve

Capture the full error and the importing file. Distinguish a bare package name, such as a library dependency, from a relative path such as ./worker. A package installation cannot create the local worker file that your build failed to emit or reference correctly.

Inspect the files inside the runtime artifact, not only the source tree. Bundlers and development loaders can perform resolution that plain Node does not. The acceptance command for a deployed Node process should include running the actual emitted entrypoint with the target Node runtime.

Relative ESM imports need explicit file paths

Node’s native ECMAScript module resolution requires file extensions for relative and absolute import specifiers. It does not automatically turn ./worker into ./worker.mjs or an index file. A directory import must name the actual file when using this resolution model.

This is separate from how a package exposes public entrypoints through its package.json exports field. Do not blindly append .js to every third-party package import. First identify whether the specifier is a local file or a package contract.

Use a minimal native-ESM comparison

The code block below labels the contents of two separate files: worker.mjs and main.mjs. Create them separately in a disposable directory, not as one combined module. The intentionally extensionless import isolates local-file resolution from packages or a build tool.

The corrected import names the file that exists. Success should produce the number 42. A successful test here demonstrates the local-file resolution rule; it does not validate the contents of your production build.

javascript · ÖRNEK

// worker.mjs
export function run() {
  return 42;
}

// main.mjs: fails under native ESM resolution
import { run } from './worker';
console.log(run());

// Correct main.mjs to import the actual file:
// import { run } from './worker.mjs';

Make module mode and emitted files agree

For JavaScript files, make the package’s module mode explicit. The .mjs extension identifies an ES module; .cjs identifies CommonJS. The nearest applicable package.json and its type field matter for .js files. A build copied without its expected package metadata can therefore change the runtime interpretation.

If source is compiled from TypeScript, verify the generated JavaScript import paths and the selected module-resolution mode. A source import ending in .ts is not automatically correct for a runtime artifact containing only .js files. Use the compiler or bundler’s documented output model rather than a post-build search-and-replace.

Inspect the exact path, including case

Check whether the referenced file exists relative to the importing output file and whether its letter case matches. A path that happens to work on a case-insensitive development filesystem can fail in a Linux container. Also check whether the Docker copy step excluded the relevant output directory.

For a missing package, investigate the production dependency set and the package’s exported entrypoints instead. An import blocked by package exports or a missing dependency is a different failure from an extensionless local ESM import. Keep the error code and unresolved specifier in the diagnosis.

Verify without the development loader

Run the entrypoint using plain Node inside the built image or clean deployment artifact. Exercise the code path that previously imported the missing module, especially if the import is dynamic and not reached at startup. Confirm that the successful command does not rely on a global loader or a developer-only tool.

The repair is complete when the emitted artifact resolves its own files under the intended runtime configuration. Reinstalling packages, switching module systems, or adding experimental resolution flags without establishing the broken path can obscure that evidence.

Sınırları bil

This guide concerns native Node ESM file resolution. Bundlers, custom loaders, TypeScript execution tools, package exports, and CommonJS use different rules. The two-file example is intentionally minimal and uses no external dependencies.

Kaynaklar ve ileri okuma

CoreTrailKit tarafından hazırlanan teknik yayın.

Bütün yazıları keşfet