できない.dev

Node.js「Error: Cannot find module」の原因と直し方

Error: Cannot find module は、起動位置を package.json に合わせるか、依存を npm install すれば直ることが多い。
ESM と CommonJS の取り違えも疑い、npm ls で切り分ける。

公開: 更新:

症状できない · exit 1
node app.js
…
Error: Cannot find module './does-not-exist'
Require stack:
- /tmp/tmp.aXEShc4YUD/app.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1207:15)
解決後できた · exit 0
node -e "console.log('loaded:', require('./does-not-exist.js'))"
loaded: 42

2026-11-15 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細

要約

Error: Cannot find module 'foo' の対処は、まず その foo が node の解決経路にあるか を確認することから始める。
原因は、実行位置のズレ、依存定義の欠落、モジュールシステムの不一致の 3 系統に概ね分かれる。
順に切り分ければ大半が片付く。

実行例

node:20 環境で上記の手順を動かすと、require('./does-not-exist') を含む app.js が Error: Cannot find module './does-not-exist'(終了コード 1)で失敗した。
参照先ファイルを作成して再実行すると、loaded: 42 を出力して正常終了(終了コード 0)した。

$ node app.js
node:internal/modules/cjs/loader:1210
  throw err;
  ^
 
Error: Cannot find module './does-not-exist'
Require stack:
- /tmp/tmp.aXEShc4YUD/app.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1207:15)
    at Module._load (node:internal/modules/cjs/loader:1038:27)
    at Module.require (node:internal/modules/cjs/loader:1289:19)
    at require (node:internal/modules/helpers:182:18)
    at Object.<anonymous> (/tmp/tmp.aXEShc4YUD/app.js:1:1)
    at Module._compile (node:internal/modules/cjs/loader:1521:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1623:10)
    at Module.load (node:internal/modules/cjs/loader:1266:32)
    at Module._load (node:internal/modules/cjs/loader:1091:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:164:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/tmp/tmp.aXEShc4YUD/app.js' ]
}
 
Node.js v20.20.2
$ echo $?
1
$ node -e "console.log('loaded:', require('./does-not-exist.js'))"
loaded: 42
$ echo $?
0
$ node -e "console.log(require.resolve('./does-not-exist.js'))"
/tmp/tmp.aXEShc4YUD/does-not-exist.js

— 2026-11-15 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-11-15 検証(ほか 1 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 解決経路を可視化する

node -e "console.log(require.resolve('foo'))"

期待しない場所が出れば、NODE_PATH や workspace 構造を疑う。
エラーになる場合はそもそも install されていない。
Node が node_modules を上方向に再帰探索する仕組みは 公式 Modules ドキュメント(新しいタブで開く) に記載されている。

2. 依存の存在確認と追加

npm ls foo
# foo が出なければ
npm install foo

本番モードで起動するなら dependencies に置く。
devDependencies だけだと npm ci --omit=dev 環境で消える。

3. ESM / CJS をどちらかに揃える

// package.json: "type":"module"
import foo from "foo";
import { helper } from "./util.js";   // 拡張子必須

CJS のままにするなら "type":"commonjs" に戻し、require() で書く。
混ぜない。

4. workspaces / monorepo の場合

npm install foo --workspace=packages/web

ルートから一括で入れるとホイストの挙動が読みにくいので、対象 workspace を明示すると確実に正しい階層に入る。

よくある原因

  1. 作業ディレクトリが違う。
    npm install した場所と node の起動位置が別で、node_modules が見つからない。
  2. 依存が欠けている。
    package.json に書かれていないか、devDependencies に入れたまま NODE_ENV=production で起動している。
  3. ESM/CJS が混在している。
    "type":"module" を付けたのに require() を使っているか、ESM で拡張子を省略している。
  4. monorepo / workspaces でホイストされている。
    親側の node_modules に上げられて、子パッケージから見えない。