Error [ERR_MODULE_NOT_FOUND]: Cannot find module

What is ERR_MODULE_NOT_FOUND?

ERR_MODULE_NOT_FOUND is thrown exclusively by Node.js's native ES module (ESM) loader when an import statement or import() call cannot be resolved to a file or package. It is the ESM counterpart to the CommonJS MODULE_NOT_FOUND code.

The critical difference: the ESM loader is strict. It does not automatically try adding .js, look for /index.js in directories, or fall back to other extensions. Every specifier must exactly name a resolvable file.

Full Error Example

node:internal/modules/esm/resolve:838
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
  ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module './utils' imported from /app/index.js
Did you mean to import ./utils.js?
    at packageResolve (node:internal/modules/esm/resolve:838:9)
    at moduleResolve (node:internal/modules/esm/resolve:907:20)
    at defaultResolve (node:internal/modules/esm/resolve:1038:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:557:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:530:38)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:246:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///app/utils'
}

Since Node.js 18, the error message sometimes includes a hint: "Did you mean to import ./utils.js?" — a strong signal that a missing extension is the root cause. The error object also carries a url field containing the unresolved specifier as a file:// URL.

ERR_MODULE_NOT_FOUND vs MODULE_NOT_FOUND

All Causes at a Glance

Cause 1 – Missing .js Extension in Relative Import

This is the single most common cause. The ESM specification requires that relative specifiers include the full file extension — there is no fallback resolution. Node.js will not try ./utils.js just because ./utils was requested.

CommonJS vs ESM resolution side by side

// CommonJS (require) — extension is optional
const utils = require('./utils');   // Node.js tries utils.js, utils.json, utils/index.js
const utils = require('./utils.js'); // also works

// ESM (import) — extension is MANDATORY for relative specifiers
import { helper } from './utils';    // ERR_MODULE_NOT_FOUND: Cannot find module './utils'
import { helper } from './utils.js'; // correct

Common patterns that need updating

// Before (worked in CJS, fails in ESM)
import { formatDate } from './helpers/format';
import config from '../config';
import * as db from './db/index';

// After (ESM-compliant)
import { formatDate } from './helpers/format.js';
import config from '../config.js';
import * as db from './db/index.js';

Cause 2 – TypeScript: Wrong moduleResolution Setting

This is the #1 TypeScript ESM pain point. TypeScript does not rewrite import paths during compilation — whatever you write in the .ts source is emitted verbatim into the compiled .js output. If you wrote import { x } from './utils' (no extension), the compiled output also has no extension, and Node.js's ESM loader throws ERR_MODULE_NOT_FOUND.

The three moduleResolution options and what they mean for ESM

Correct tsconfig.json for Node.js ESM

// tsconfig.json — recommended for Node.js ESM projects
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",          // or "NodeNext"
    "moduleResolution": "Node16", // or "NodeNext" — must match module
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true
  }
}

TypeScript source file — use .js extension even though source is .ts

// src/index.ts
// Import uses .js extension — TypeScript resolves this to src/utils.ts at compile time
// The compiled dist/index.js will contain: import { helper } from './utils.js'
// which correctly references dist/utils.js at runtime

import { helper } from './utils.js';   // correct — .js refers to the compiled output
import { helper } from './utils.ts';   // wrong — TypeScript rejects this
import { helper } from './utils';      // wrong — ERR_MODULE_NOT_FOUND at runtime

Correct tsconfig.json for bundler-based projects (Vite, esbuild, tsup)

// tsconfig.json — for projects where a bundler handles resolution
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",  // bundler handles extensions, not Node.js
    "outDir": "./dist",
    "strict": true
  }
}

Cause 3 – Missing "type": "module" in package.json

Without "type": "module", Node.js treats .js files as CommonJS. An import statement in a CJS file throws SyntaxError: Cannot use import statement outside a module, not ERR_MODULE_NOT_FOUND. However, the missing field is still a common root cause that puts the whole project on the wrong loader path.

// package.json — required for ESM
{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",   // ← enables ESM for all .js files in this package
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Without "type": "module", use .mjs extension for individual ESM files instead of .js. The .mjs extension always forces ESM regardless of the type field.

// Option 1: use "type": "module" in package.json → all .js files are ESM
// Option 2: rename individual files to .mjs → those files are ESM
// Option 3: keep CJS and use dynamic import() for ESM packages

// Mixing .mjs and .cjs in one project
import { esm } from './helper.mjs';          // forced ESM
const cjs = require('./legacy.cjs');          // forced CJS (inside a .cjs file)
const esmPkg = await import('./utils.mjs');   // dynamic import from CJS file

Cause 4 – Directory Import (No Automatic index.js in ESM)

In CommonJS, require('./models') automatically resolves to ./models/index.js if models is a directory. The ESM loader does not do this — ERR_UNSUPPORTED_DIR_IMPORT is thrown instead (or ERR_MODULE_NOT_FOUND if the directory itself doesn't exist).

// Wrong — ESM does not resolve directories to index.js
import * as models from './models';
import * as models from './models/';

// Correct — explicit file path
import * as models from './models/index.js';

// Also correct — add a package.json inside the directory
// models/package.json:
// { "type": "module", "exports": { ".": "./index.js" } }
// Then: import * as models from './models'; works via exports map

Cause 5 – Package Not Installed

When importing a third-party package and the package is not installed, the ESM loader throws Cannot find package 'package-name'. This behaves identically to the CJS case.

# The error
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from /app/index.js

# Fix
npm install express
# or
yarn add express
# or
pnpm add express

// After installing, the ESM import works normally
import express from 'express';
import { Router } from 'express';

Cause 6 – Missing or Incomplete Package exports Map

Modern packages use the "exports" field in package.json to declare which subpaths can be imported. If you try to import a path not listed in exports, the ESM loader throws ERR_MODULE_NOT_FOUND (or ERR_PACKAGE_PATH_NOT_EXPORTED if the package has an exports map but the specific path is missing).

// Error: Cannot find package 'some-pkg/internal/utils' imported from /app/index.js
// because package.json exports does not include that path

// package.json (in node_modules/some-pkg)
{
  "exports": {
    ".": "./dist/index.js",
    "./helpers": "./dist/helpers.js"
    // "./internal/utils" is NOT listed — importing it throws ERR_MODULE_NOT_FOUND
  }
}

// Fix option 1: use a public export path
import { helper } from 'some-pkg/helpers';

// Fix option 2: if you control the package, add the export
{
  "exports": {
    ".": "./dist/index.js",
    "./helpers": "./dist/helpers.js",
    "./internal/utils": "./dist/internal/utils.js"  // added
  }
}

// Fix option 3: use createRequire to bypass the exports map (CJS packages only)
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const utils = require('some-pkg/internal/utils');

Cause 7 – CJS-only Package Imported in ESM Context

Some older or niche packages are CommonJS-only and have no ESM export in their package.json. Node.js's ESM loader can still load them — CJS packages are interoperable with ESM via the default export. If the error fires, the package is likely not installed, or its "main" field points to a non-existent file.

// CJS packages CAN be imported in ESM — no special handling needed in most cases
import lodash from 'lodash';           // works — lodash is CJS
import { merge } from 'lodash';        // also works (named imports from CJS default export)

// If the package has no ESM build AND its main field is broken, use createRequire
import { createRequire } from 'module';
const require = createRequire(import.meta.url);

const legacyPkg = require('legacy-cjs-only-package');
const { specificExport } = require('another-cjs-package/lib/specific');

Cause 8 – TypeScript with ts-node (CJS Hook Active)

By default, ts-node registers a CommonJS hook. When your project has "type": "module", ts-node may fail or fall back in unexpected ways. The compiled or interpreted output then runs through the ESM loader with bare specifiers that were fine under the CJS hook but fail under strict ESM.

Option A — Use tsx (recommended for development)

# Install tsx
npm install --save-dev tsx

# Run TypeScript ESM files directly — no tsconfig tweaks needed
npx tsx src/index.ts

# Or add to package.json scripts
{
  "scripts": {
    "dev": "tsx src/index.ts",
    "dev:watch": "tsx watch src/index.ts"
  }
}

Option B — Use node --experimental-strip-types (Node.js 22.6+)

# Node.js 22.6+ can strip TypeScript types natively (no compilation step)
node --experimental-strip-types src/index.ts

# Node.js 23.6+ — no flag needed
node src/index.ts

Option C — Configure ts-node for ESM mode

// tsconfig.json — ts-node ESM configuration
{
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "Node16",
    "target": "ES2022"
  },
  "ts-node": {
    "esm": true,
    "experimentalSpecifierResolution": "node"  // only if needed for legacy imports
  }
}

// Run with:
// node --loader ts-node/esm src/index.ts
// or:
// ts-node-esm src/index.ts

Option D — Compile with tsc and run compiled output

# Build TypeScript to JavaScript
npx tsc

# Run the compiled output (Node.js reads dist/index.js with .js extensions intact)
node dist/index.js

Cause 9 – Case Sensitivity on Linux / CI

macOS (HFS+/APFS default) and Windows (NTFS default) are case-insensitive. Linux is case-sensitive. An import of ./Utils.js when the file is utils.js works locally but throws ERR_MODULE_NOT_FOUND in CI (usually Ubuntu) or in a Docker container (usually Alpine/Debian Linux).

// File on disk: src/utils.js

// Wrong — works on macOS/Windows, throws ERR_MODULE_NOT_FOUND on Linux
import { helper } from './Utils.js';
import { helper } from './UTILS.js';

// Correct — matches the actual filename on disk exactly
import { helper } from './utils.js';

Use eslint-plugin-import with the import/no-unresolved rule (or TypeScript's forceConsistentCasingInFileNames compiler option) to catch case mismatches at lint/compile time before they reach CI.

Safe ESM Import Patterns

Relative imports — always use .js

// src/server.ts (TypeScript, compiled to dist/server.js)
import { createApp } from './app.js';           // compiled: dist/app.js
import { db } from './db/connection.js';        // compiled: dist/db/connection.js
import { UserSchema } from './schemas/user.js'; // compiled: dist/schemas/user.js
import type { Config } from './types.js';       // type-only import, erased at compile time

ESM entry point pattern with package.json exports

// package.json
{
  "name": "my-library",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./helpers": {
      "import": "./dist/helpers.js",
      "types": "./dist/helpers.d.ts"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.js"
}

ESM + CJS hybrid package (dual build)

// tsup.config.ts — build both ESM and CJS from TypeScript source
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],    // produce both .cjs and .js
  dts: true,                  // generate .d.ts files
  splitting: false,
  sourcemap: true,
  clean: true,
});

Using import.meta.url instead of __dirname in ESM

// In ESM, __dirname and __filename are not available
// Use import.meta.url instead

import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Now use __dirname as you would in CJS
const configPath = join(__dirname, '../config/default.json');

// Or use URL directly — often cleaner in ESM
const configURL = new URL('../config/default.json', import.meta.url);
import config from '../config/default.json' with { type: 'json' };

Dynamic import() for conditional loading

// Dynamic import works in both CJS and ESM files
// Useful for loading ESM-only packages from CJS, or for lazy loading

async function loadModule(name) {
  try {
    const mod = await import(name);
    return mod.default ?? mod;
  } catch (err) {
    if (err.code === 'ERR_MODULE_NOT_FOUND') {
      console.error(`Module '${name}' not found. Run: npm install ${name}`);
      process.exit(1);
    }
    throw err;
  }
}

// Example: load chalk (ESM-only) from a CJS file
const chalk = await loadModule('chalk');

Debugging Checklist

1. Read the "imported from /path/to/file.js" part of the message — it tells you exactly which file has the bad import. Open that file and find the import statement.
2. Check if Node.js is hinting: "Did you mean to import ./utils.js?" — if yes, add the .js extension immediately.
3. Confirm the file actually exists on disk with the exact casing. On Linux/CI, case matters.
4. Check package.json for "type": "module" — without it, .js files run as CJS.
5. For TypeScript projects: check tsconfig.json — is module and moduleResolution set to Node16 or NodeNext?
6. For TypeScript: is the compiled output in dist/ missing the .js extension in imports? If so, the tsconfig settings are wrong.
7. Is it a package (not a relative file)? Run npm ls <package-name> to confirm it's installed locally.
8. Is it a subpath import like pkg/lib/utils? Check if that path is listed in the package's "exports" field.
9. Is it a directory import (./models pointing to a folder)? Rewrite as ./models/index.js.
10. Run node --input-type=module <<< "import './your-file.js'" to test ESM resolution in isolation.

Frequently Asked Questions

// src/index.ts
import { helper } from './utils.js'; // .js = compiled output, not source

import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const internal = require('legacy-pkg/lib/internal');

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["node", "dist/index.js"]

Related Errors

• MODULE_NOT_FOUND – the CommonJS require() counterpart; thrown when require() cannot find a module (extensions optional, index.js auto-resolved)
• ERR_UNSUPPORTED_DIR_IMPORT – thrown when an ESM import targets a directory that exists (as opposed to a path that doesn't exist at all)
• ERR_PACKAGE_PATH_NOT_EXPORTED – package is installed but the specific subpath is not in the exports map
• ERR_REQUIRE_ESM – opposite direction: using require() on a file that is ESM-only
• SyntaxError: Cannot use import statement outside a module – using import in a file that Node.js treats as CJS (missing "type":"module")
• ERR_UNKNOWN_FILE_EXTENSION – ESM loader encounters a .ts or other non-native extension it cannot execute
• ERR_INVALID_PACKAGE_CONFIG – malformed package.json causing module resolution to fail before the file lookup