Node.js「Error: Cannot find module」の原因と直し方
Error: Cannot find module は、起動位置を package.json に合わせるか、依存を npm install すれば直ることが多い。
ESM と CommonJS の取り違えも疑い、npm ls で切り分ける。
公開: 更新:
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)
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:20Debian 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 を明示すると確実に正しい階層に入る。
よくある原因
- 作業ディレクトリが違う。
npm installした場所とnodeの起動位置が別で、node_modulesが見つからない。 - 依存が欠けている。
package.jsonに書かれていないか、devDependenciesに入れたままNODE_ENV=productionで起動している。 - ESM/CJS が混在している。
"type":"module"を付けたのにrequire()を使っているか、ESM で拡張子を省略している。 - monorepo / workspaces でホイストされている。
親側の node_modules に上げられて、子パッケージから見えない。