結論
Module not found: Can't resolve 'X' は、import に書いた「X」を、webpack などのバンドラーが実際のファイルに結び付けられなかったときのエラーです。引用符の中の X が「./」で始まるならパス・大文字小文字・拡張子、「@/」ならエイリアス、パッケージ名ならインストール・Node.js の組み込みモジュール・exports を疑うと、ほとんどの場合すぐに原因が絞れます。
この記事でわかること
- 原因8つを webpack・Vite・Next.js で実際に出したエラーの原文と、直した後の出力
- 引用符の中身から原因を絞る5分の手順と、ツールごとのエラー文の違い
- Windows・Mac では動くのに Linux・CI だけ失敗する理由と、モノレポでの直し方
この記事で実際に動かしたもの:webpack 5.112.2・Vite 8.3.5・Next.js 16.4.5 の3つで、同じ8種類の import の誤りを起こし、エラーの原文と、直したあとのビルド結果を取りました。
flowchart LR
A["'./' '../' で始まる"] --> A2[パス・大文字小文字<br>拡張子を見る]
B["'@/' で始まる"] --> B2[バンドラーにも<br>エイリアスを書く]
C[パッケージ名] --> C2[npm ls で確かめ<br>無ければ install]
D["fs・path など"] --> D2[ブラウザから外し<br>サーバー側へ]
図は、エラーの引用符の中身(X)の書き出しごとに、最初に見る場所を示したものです。
よく調べられることの答えを先にまとめます。
| やりたいこと | いちばん早い方法 | 詳しい節 |
|---|---|---|
| Can't resolve の意味を知りたい | 引用符の中の名前が、ファイルにもパッケージにも見つからないという意味 | Module not found: Can't resolve とは |
| パッケージ名で出た | npm ls 名前 で確かめ、無ければ npm install 名前 |
原因1:パッケージが未インストール |
| 自分のファイルなのに出た | ls でファイル名の大文字小文字と場所を見比べる |
原因2・3:パスの間違いと大文字小文字 |
| Windows・Mac では動くのに CI で出た | 大文字小文字の違いを直し、git mv で名前を変える |
原因2・3:パスの間違いと大文字小文字 |
| @/ の import で出た | tsconfig の paths だけでなく、バンドラー側にも設定する | 原因5:エイリアス @/ が解決できない |
| Can't resolve 'fs' と出た | ブラウザで動くコードから fs を外し、サーバー側へ移す | 原因6:fs・path などの組み込みモジュール |
| Vite の Failed to resolve import | 同じ原因。パスとエイリアス(resolve.alias か tsconfigPaths)を見る | Vite の Failed to resolve import |
| Next.js の Module not found | jsconfig・tsconfig の paths と、'use client' の中の fs を見る | Next.js の Module not found |
確認環境:Ubuntu 24.04.5 LTS の上で、Node.js 22.23.4・npm 10.9.9 を使いました。webpack 5.112.2(webpack-cli 7.3.1)、Vite 8.3.5(同梱の Rolldown でビルド)、Next.js 16.4.5(React 19.3.1)をそれぞれ別のフォルダーに入れ、未インストールのパッケージ・大文字小文字の違い・拡張子・@/ エイリアス・fs と path・package.json の exports・npm workspaces のモノレポで、エラーを実際に出しました。原文の中の作業フォルダーのパスは /app(モノレポは /repo)に置き換えています。Next.js は作業場所の容量の都合でネイティブの SWC バイナリ(約100MB)を入れず、公式に配布されている @next/swc-wasm-nodejs を使って next build --webpack と next dev --webpack(127.0.0.1 で起動)で実行しました。Next.js 16 の既定の Turbopack は今回は動かしておらず、Turbopack の設定(resolveAlias・root)は Next.js の公式ドキュメントで確かめています。Vite の開発サーバーも 127.0.0.1 で起動し、curl でモジュールを要求して応答を見ました。Windows・Mac の挙動(大文字小文字を区別しないファイルシステム)は手元で動かせないため、webpack が出したエラー文と、Vite・Next.js の公式ドキュメントの記述の範囲で書いています。図は mermaid 11.16.0 で描画を確かめました(確認日 2026年11月5日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Module not found: Can't resolveの原因8つと直し方」
Module not found: Can't resolve とは(エラー文の読み方)
この節では、Module not found: Can't resolve の各部分が何を表しているかと、webpack・Vite・Next.js でエラー文がどう違うかが分かります。
Module not found: Can't resolve 'X' in 'Y' は、「Y のフォルダーにあるファイルが X を import しているが、X に当たるファイルが見つからない」という意味です。resolve(解決)とは、import に書いた文字列を、実際のファイルの場所に置き換える作業のことです。バンドラーは import を1つずつ解決してから1本のファイルにまとめるので、1つでも解決できないとビルドが止まります。
webpack 5.112.2 で、インストールしていない dayjs を import したときの原文です(先頭の部分)。
ERROR in ./src/index.js 1:0-26
Module not found: Error: Can't resolve 'dayjs' in '/app/src'
resolve 'dayjs' in '/app/src'
Parsed request is a module
using description file: /app/package.json (relative path: ./src)
Field 'browser' doesn't contain a valid alias configuration
resolve as module
/app/src/node_modules doesn't exist or is not a directory
looking for modules in /app/node_modules
single file module
using description file: /app/package.json (relative path: ./node_modules/dayjs)
no extension
Field 'browser' doesn't contain a valid alias configuration
/app/node_modules/dayjs doesn't exist
.ts
...
webpack 5.112.2 compiled with 1 error in 161 ms
読む場所は3つです。
11行目は「どのファイルの何行目か」
./src/index.js 1:0-26 は、src/index.js の1行目、0〜26文字目の import が原因という意味。直す場所はここ。
2引用符の中は「書いた文字列そのまま」
'dayjs' や './components/header' は、ソースに書いた文字列。ここが原因を絞るいちばんの手がかりになる。
3下に続く行は「探した場所の記録」
doesn't exist の並びは、どのフォルダーでどの拡張子を試したかの記録。どこを探して見つからなかったかが分かる。
同じ誤りでも、ツールによって文言が変わります。検索するときは、自分の画面に出ている文言で探すと見つけやすくなります。
| ツール・場面 | 実際に出た文言(パッケージが無いとき) | ビルドの結果 |
|---|---|---|
| webpack 5.112.2 | Module not found: Error: Can't resolve 'dayjs' in '/app/src' | 終了コード1。ただし main.js は出力される |
| Next.js 16.4.5(webpack) | Module not found: Can't resolve 'dayjs' | Failed to compile. で止まる |
| Vite 8.3.5 開発サーバー | Failed to resolve import "dayjs" from "src/main.js". Does the file exist? | そのモジュールの要求に HTTP 500 |
| Vite 8.3.5 ビルド(パッケージ名) | [vite]: Rolldown failed to resolve import "dayjs" from "/app/src/main.js". | Build failed で止まる |
| Vite 8.3.5 ビルド(相対パス) | [UNRESOLVED_IMPORT] Could not resolve './components/header' | Build failed で止まる |
似た名前のエラーに、Node.js の Error: Cannot find module 'X' があります。こちらはバンドラーではなく、node app.js のように Node.js が直接ファイルを読み込むときのエラーです。実は webpack は、解決できなかった import を「実行すると Cannot find module を投げるコード」に置き換えて main.js を出力します。エラーのまま出力された main.js を node で動かすと、次のようになりました。
$ node dist/main.js
Error: Cannot find module 'dayjs'
at webpackMissingModule (/app/dist/main.js:128:52)
...
code: 'MODULE_NOT_FOUND'
ビルドのエラーを見落としてデプロイすると、実行したときに初めてこのエラーが出ます。CI では終了コード(webpack は1を返した)でビルドを止めるようにしておくと安全です。Node.js 側の Cannot find module については、関連記事「Node.js Cannot find moduleの原因と直し方」で扱っています。
原因8つの一覧と、引用符の中身での見分け方
この節では、Module not found: Can't resolve の原因8つと、それぞれがどんな文言・場面で出るかが一覧で分かります。
この環境で再現できた原因は次の8つです。引用符の中身の書き出しで、まず左の列のどれかに絞れます。
| 引用符の中身 | 原因 | 手がかりになる文言 | 直し方 |
|---|---|---|---|
| パッケージ名 | 1. インストールしていない | node_modules/名前 doesn't exist | npm install 名前 |
| ./ や ../ | 2. パス(階層・綴り)の間違い | Can't resolve './…' | import 元から見た相対パスに直す |
| ./ や ../ | 3. 大文字小文字の違い | differs from the request only in casing | ファイル名と同じ大文字小文字に |
| ./ や ../ | 4. 拡張子を解決できない | .jsx が試されていない/fully specified | 拡張子を書くか、resolve.extensions |
| @/ や ~/ | 5. エイリアスがバンドラーに無い | node_modules/@/components doesn't exist | resolve.alias か paths を設定 |
| fs・path など | 6. Node.js の組み込みをブラウザで使った | BREAKING CHANGE: webpack < 5 used to include polyfills | サーバー側へ移すか fallback |
| パッケージ名/深いパス | 7. exports で公開されていない | is not exported under the conditions | 公開されたパスで import |
| 社内パッケージ名 | 8. モノレポで未インストール・未ビルド | use ./dist/index.js from main … doesn't exist | ルートで npm install・ビルド |
引用符の中身が components/Header のように「./」なしで始まる場合は、原因2の一種です。webpack は「./」の無い名前をパッケージ名として node_modules の中を探すため、自分のファイルでも見つかりません。
自分のファイルの問題(原因2〜5)
引用符の中が ./ ../ @/ で始まる
ls でファイルの実物と見比べれば分かる
直すのは import の行か、バンドラーの設定
パッケージの問題(原因1・6〜8)
引用符の中がパッケージ名で始まる
npm ls と node_modules の中身で分かる
直すのはインストール・置き場所・import のパス
最初の5分で切り分ける手順
この節では、エラーが出た直後に、どの順番で何を確かめれば原因に早くたどり着けるかが分かります。
1行目のファイルと、引用符の中身を控える
例:./src/index.js が './components/header' を探している。エラーが複数あるときは、いちばん上から1つずつ直す(1つの原因で複数出ることがある)。
パッケージ名なら npm ls で入っているか見る
npm ls dayjs の結果が (empty) なら未インストール。package.json に書いてあるのに入っていないなら npm install を流し直す。
自分のファイルなら ls で実物と見比べる
ls src/components | grep -i header のように大文字小文字を無視して探し、実際のファイル名・拡張子・置き場所と import の文字列を1文字ずつ比べる。
@/ ならバンドラーの設定を開く
tsconfig.json・jsconfig.json の paths と、webpack の resolve.alias、Vite の resolve.alias または resolve.tsconfigPaths のどちらにも書いてあるかを見る。
fs・path・crypto ならどこで動くコードか考える
ブラウザで動くコード(Next.js の 'use client' の中、Vite・webpack のフロントエンド)から Node.js の組み込みモジュールを読んでいないかを見る。
手元で確かめるコマンドは次の2つが便利です。どちらもこの環境で実行しました。
# パッケージが入っているか(入っていなければ (empty) と終了コード1)
$ npm ls dayjs
vt@1.0.0 /app
`-- (empty)
# 大文字小文字を無視してファイルを探す
$ ls src/components | grep -i header
Header.js
原因1:パッケージが未インストール(npm install で直す)
この節では、パッケージ名で Can't resolve が出たときに、インストールの有無を確かめて直す方法が分かります。
いちばん多い原因は、import したパッケージが node_modules に入っていないことです。他の人のリポジトリを clone した直後、ブランチを切り替えて package.json が変わった直後、ほかの記事のコードを貼り付けた直後によく起こります。
webpack の原文では、looking for modules in /app/node_modules の下に /app/node_modules/dayjs doesn't exist が出ています。その後、親のフォルダーへ順に上がりながら node_modules を探し、最後は /node_modules doesn't exist or is not a directory で終わります。どこにも無かった、という記録です。
直し方はインストールです。
$ npm install dayjs
added 1 package in 576ms
$ npx webpack
asset main.js 12.9 KiB [emitted] (name: main)
./node_modules/dayjs/dayjs.min.js 6.99 KiB [built] [code generated]
webpack 5.112.2 compiled successfully in 189 ms
package.json にはあるのに入っていない場合は、名前を指定せずに npm install(CI では npm ci)で package-lock.json どおりに入れ直します。それでも直らないときは、node_modules と各ツールのキャッシュ(node_modules/.vite、node_modules/.cache、.next)を消してから入れ直します。
# macOS・Linux・Git Bash
rm -rf node_modules .next node_modules/.vite
npm install
# Windows(コマンドプロンプト)
rmdir /s /q node_modules
npm install
インストールのときに npm ERR! ERESOLVE が出て止まる場合は、依存関係(peer 依存)のぶつかりが先の問題です。関連記事「npm ERR! ERESOLVEの原因と直し方|peer依存の読み方」で扱っています。
グローバルに入れれば直る、とは限らない
npm install -g dayjs で入れて済ませる。バンドラーはプロジェクトの node_modules を親へたどって探すため、グローバルの置き場所は探さないnpm install dayjs を実行し、package.json の dependencies に残す。ほかの人や CI でも同じ状態になる見分ける問い:「package.json に書いてあるか」
原因2・3:パスの間違いと大文字小文字(Linux・CIだけ失敗する理由)
この節では、自分で作ったファイルの import で Can't resolve が出る原因と、Windows・Mac では動くのに Linux や CI だけで失敗する理由が分かります。
相対パスの基準は「import を書いたファイルの場所」
相対パスは、プロジェクトのルートではなく、import を書いたファイルがあるフォルダーから数えます。src/pages/About.js から src/components/Header.js を読むなら '../components/Header' です。'./components/Header' と書くと src/pages/components を探して失敗します。
「./」を付け忘れたときは、webpack 5.112.2 が次のように教えてくれました。
ERROR in ./src/index.js 1:0-39
Module not found: Error: Can't resolve 'components/Header' in '/app/src'
Did you mean './components/Header'?
Requests that should resolve in the current directory need to start with './'.
Requests that start with a name are treated as module requests and resolve within module directories (node_modules).
If changing the source code is not an option there is also a resolve options called 'preferRelative' which tries to resolve these kind of requests in the current directory too.
文言にある resolve.preferRelative: true を設定すると、同じ import でもビルドが通りました(compiled successfully in 119 ms)。ただし、同じ名前のパッケージがあると取り違えるおそれがあるため、まずは「./」を付ける直し方を選びます。
大文字小文字の違いは Linux で初めて表に出る
ファイル名は Header.js なのに、'./components/header' と書いたときの原文です。webpack 5.112.2 は、大文字小文字だけが違うファイルがあることまで示しました。
ERROR in ./src/index.js 1:0-41
Module not found: Error: Can't resolve './components/header' in '/app/src'
Did you mean './components/Header.js'?
'Header.js' exists in that directory and differs from the request only in casing. Case-sensitive filesystems (most Linux ones) fail to resolve it, even when the same build succeeds on a case-insensitive one.
Windows と Mac の標準のファイルシステムは大文字小文字を区別しないため、この import でも手元では動きます。Linux の CI や Docker のコンテナ、本番のサーバーでビルドしたときに初めて失敗するのはこのためです。Next.js の公式ドキュメントも、大文字小文字の誤りは「多くの Linux ベースの CI のような、大文字小文字を区別する環境でビルドの失敗につながる」と書いています。Vite の公式ドキュメントのトラブルシューティングにも、同じ理由の項目があります。
直し方は、import の文字列をファイル名に合わせることです。ファイル名のほうを変えたいときは、Git に名前の変更を確実に記録させるため git mv を使います。
$ git mv c/header.js c/Header.js
$ git status --short
R c/header.js -> c/Header.js
Windows・Mac で単にファイル名の大文字小文字だけを変えると、Git の設定(core.ignorecase)によっては変更として記録されず、リポジトリの中は以前の名前のまま残ることがあります。git ls-files で Git が記録している名前を見ると確かめられます。
原因4:拡張子が解決されない(resolve.extensions・fully specified)
この節では、拡張子を省いた import が失敗する2つのパターンと、それぞれの直し方が分かります。
パターン1:試す拡張子の一覧に入っていない
拡張子を省いた import では、バンドラーが決まった順番で拡張子を足して探します。一覧に無い拡張子のファイルは見つかりません。この環境で取り出した既定値は次のとおりです。
| ツール | 省略時に試す拡張子(既定) | 確かめ方 |
|---|---|---|
| webpack 5.112.2(import 文) | .ts .js .json .wasm .html .css | webpack の既定値を適用した設定を Node.js で出力 |
| webpack(公式ドキュメントの記載) | .js .json .wasm | webpack.js.org の resolve.extensions |
| Vite 8.3.5 | .mjs .js .mts .ts .jsx .tsx .json | vite の配布物の DEFAULT_EXTENSIONS と公式ドキュメント |
| Next.js(Turbopack) | .tsx .ts .jsx .js .mjs .json | Next.js 公式ドキュメントの turbopack.resolveExtensions |
webpack 5.112.2 では、import 文の既定に .ts が入っていて、import { add } from './util' で util.ts がそのまま読み込まれました(Node.js の型の除去の機能を使う旨の警告つき)。公式ドキュメントの既定値の表記と違うため、版によって変わる点として覚えておくと混乱しません。一方で .jsx は既定に入っておらず、'./components/Button'(実物は Button.jsx)は Can't resolve になりました。
直し方は、拡張子を書くか、試す一覧に足すかです。webpack では '...' と書くと既定の一覧を残したまま追加できます。
// webpack.config.js
module.exports = {
resolve: {
extensions: ['.jsx', '...'], // '...' は既定の一覧。消さずに .jsx を足す
},
};
extensions: ['.jsx'] のように '...' を書かないと既定の一覧が置き換わり、今度は .js が見つからなくなります。Vite の resolve.extensions も置き換えになり、公式ドキュメントは .vue のような独自の拡張子を省くことは「推奨しない」としています。
パターン2:ESM として扱われ、拡張子が必須になる
package.json に "type": "module" を書いたプロジェクトでは、webpack は .js ファイルを厳密な ES モジュールとして扱い、拡張子を省いた相対パスを受け付けません。実際の原文です。
ERROR in ./src/index.js 1:0-41
Module not found: Error: Can't resolve './components/Header' in '/app/src'
Did you mean 'Header.js'?
BREAKING CHANGE: The request './components/Header' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
文言どおり './components/Header.js' と拡張子を書くとビルドが通りました。すぐに全部の import を書き換えられないときは、ルールで fullySpecified を外す方法もあり、こちらも通ることを確かめました。
// webpack.config.cjs("type": "module" のプロジェクトでは設定ファイルを .cjs に)
module.exports = {
module: {
rules: [{ test: /\.m?js$/, resolve: { fullySpecified: false } }],
},
};
ESM と CommonJS の違い全般は、関連記事「Node.js ESMとCommonJSの違い|import混在の解決表」で扱っています。
原因5:エイリアス @/ が解決できない(tsconfig paths だけでは足りない)
この節では、@/components/Header のようなエイリアスで Can't resolve が出る理由と、webpack・Vite・Next.js それぞれの設定方法が分かります。
tsconfig.json の paths は TypeScript(エディターの補完と型チェック)への指示で、webpack はそれを読みません。そのため、エディターでは赤線が出ないのに、ビルドすると失敗します。webpack の原文を見ると、@ をパッケージ名として node_modules の中を探していることが分かります。
ERROR in ./src/index.js 1:0-41
Module not found: Error: Can't resolve '@/components/Header' in '/app/src'
resolve '@/components/Header' in '/app/src'
Parsed request is a module
resolve as module
looking for modules in /app/node_modules
/app/node_modules/@/components doesn't exist
ツールごとの直し方は次のとおりです。すべてこの環境でビルドが通ることを確かめました。
| ツール | 設定する場所 | tsconfig の paths を自動で読むか |
|---|---|---|
| webpack | webpack.config.js の resolve.alias | 読まない(tsconfig-paths-webpack-plugin で読ませる方法もある) |
| Vite 8 | vite.config の resolve.alias、または resolve.tsconfigPaths: true | tsconfigPaths を true にしたときだけ読む(既定は false) |
| Next.js | tsconfig.json か jsconfig.json の paths | 読む(組み込みで対応) |
// webpack.config.js
const path = require('path');
module.exports = {
resolve: {
alias: { '@': path.resolve(__dirname, 'src') },
},
};
// vite.config.js(方法1:alias を書く。ESM なので __dirname ではなく import.meta.url)
import { defineConfig } from 'vite';
import { fileURLToPath, URL } from 'node:url';
export default defineConfig({
resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
});
// vite.config.js(方法2:tsconfig の paths を読ませる。Vite 8 の resolve.tsconfigPaths)
import { defineConfig } from 'vite';
export default defineConfig({ resolve: { tsconfigPaths: true } });
方法2では1つつまずきました。import を書いているのが .js ファイルだと、tsconfig.json に "allowJs": true が無い限り paths が効かず、ビルドは同じエラーのまま失敗しました。Vite の公式ドキュメントにも、tsconfigPaths が効くのは tsconfig の files・include に当てはまるファイルだけと書かれています。allowJs を足すか、ファイルを .ts にすると通りました。
| import を書いたファイル | tsconfig.json | vite build の結果 |
|---|---|---|
| src/main.js | paths だけ | Rolldown failed to resolve import "@/components/Header" |
| src/main.js | paths と allowJs: true | ✓ built in 46ms |
| src/main.ts | paths だけ(baseUrl なし) | ✓ built in 63ms |
Next.js は jsconfig.json に paths を書くだけで @/components/Header が通り、追加の設定は要りませんでした。TypeScript 側の paths・baseUrl の書き方と、エディターで赤線が出る場合の直し方は、関連記事「TypeScript pathsエイリアス設定|@/が解決できない原因と直し方」で扱っています。
原因6:fs・path などNode.jsの組み込みモジュールをブラウザで使った
この節では、Can't resolve 'fs' や 'path' が出る理由と、ツールごとの見え方の違い、正しい直し方が分かります。
fs(ファイル操作)や path は Node.js の中にだけあるモジュールで、ブラウザにはありません。バンドラーがブラウザ向けにまとめるとき、これらの import は行き先が無くなります。webpack 4 までは代わりの実装(ポリフィル)を自動で入れていましたが、webpack 5 からは入れなくなりました。
webpack 5.112.2 で fs と path を import すると、2件のエラーが出て、path のほうには次の説明が付きました。
ERROR in ./src/index.js
Module not found: Error: Can't resolve 'path' in '/app/src'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.
If you want to include a polyfill, you need to:
- add a fallback 'resolve.fallback: { "path": require.resolve("path-browserify") }'
- install 'path-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
resolve.fallback: { "path": false }
fs のほうはブラウザ向けの代わりが無いため、この説明は付かず、Can't resolve 'fs' だけが出ました。3つのツールの違いをまとめます。
| ツール | ビルド時 | 実行時 |
|---|---|---|
| webpack 5.112.2 | Can't resolve 'fs'(エラー) | fallback: false にすると空のオブジェクト {} になる |
| Vite 8.3.5 | 警告だけでビルドは成功 | fs.readFileSync に触れた時点でエラー |
| Next.js 16.4.5 | 'use client' の中なら Can't resolve 'fs' | サーバーコンポーネントの中なら動く |
Vite はビルドを止めず、次の警告を出しました。
[plugin rolldown:vite-resolve] Module "fs" has been externalized for browser compatibility, imported by "/app/src/main.js". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
✓ built in 79ms
開発サーバーが fs の代わりに返したモジュールの中身を curl で取り出すと、次のコードでした。プロパティに触れた瞬間にエラーを投げる仕組みで、ブラウザでは「Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFileSync" in client code.」のように表示されます。
export default new Proxy({}, {
get(_, key) {
throw new Error(`Module "fs" has been externalized for browser compatibility. Cannot access "fs.${key}" in client code. See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.`)
}
})
直し方の基本は、ファイルを読むような処理をサーバー側へ移すことです。ブラウザは利用者のパソコンのファイルを自由に読めないので、ポリフィルを入れても fs が本当に動くわけではありません。ライブラリが内部で path を少し使っているだけ、のように「ブラウザでは使われないと分かっている」ときに限って、resolve.fallback: { fs: false } で空のモジュールに置き換えます。
Can't resolve 'fs' の直し方
見分ける問い:「その処理はブラウザで動く必要があるか」
原因7・8:exports で公開されていないパスと、モノレポ(npm workspaces)
この節では、パッケージは入っているのに Can't resolve が出る2つの原因(package.json の exports と、モノレポの未インストール・未ビルド)が分かります。
原因7:exports に無い深いパスを import した
パッケージの package.json に exports が書かれていると、そこに並んだパスしか外から import できません。自作の mylib("." と "./utils" だけを公開)の中のファイルを直接 import したときの原文です。
ERROR in ./src/index.js 1:0-38
Module not found: Error: "./lib/internal.ts" is not exported under the conditions ["typescript","import","module-sync","module","webpack","development","browser"] from package /app/node_modules/mylib (see exports field in /app/node_modules/mylib/package.json)
書いたのは 'mylib/lib/internal.js' ですが、原文では拡張子が .ts になっていました。webpack 5.112.2 が .ts を先に試したためと考えられ、版によって表示が変わる点です。どちらにしても「is not exported」が出たら、そのパスはパッケージの作者が公開していないという意味です。公開されている 'mylib/utils' に変えるとビルドが通りました。パッケージの更新で exports が追加され、以前は動いていた深い import が急に失敗することもあります。パッケージの README や package.json の exports を見て、公開されたパスに書き換えます。
原因8:モノレポで社内パッケージが見つからない
npm workspaces で、apps/web から packages/ui(パッケージ名 @acme/ui)を使う構成を作って試しました。ルートで npm install を流す前は、node_modules に @acme/ui へのリンクが無いため、原因1と同じ Can't resolve '@acme/ui' になりました。
インストールしてリンクができても、まだ失敗しました。packages/ui の package.json が "main": "dist/index.js" を指しているのに、ビルドしておらず dist が無かったためです。原文を下までたどると、理由がそのまま書かれていました。
ERROR in ./src/index.js 1:0-34
Module not found: Error: Can't resolve '@acme/ui' in '/repo/apps/web/src'
...
as directory
existing directory /repo/node_modules/@acme/ui
using description file: /repo/node_modules/@acme/ui/package.json (relative path: .)
use ./dist/index.js from main in package.json
using description file: /repo/node_modules/@acme/ui/package.json (relative path: ./dist/index.js)
no extension
/repo/node_modules/@acme/ui/dist/index.js doesn't exist
packages/ui をビルドして dist/index.js を作ると、compiled successfully in 161 ms になり、出力を node で動かすと ui-button と表示されました。モノレポでは「ルートで npm install したか」「依存先のパッケージをビルドしたか」「main・exports が実在するファイルを指しているか」の3つを順に見ます。
Next.js の Turbopack は、プロジェクトのルートの外にあるファイルを解決しません。公式ドキュメントによると、ルートは pnpm-lock.yaml・package-lock.json・yarn.lock などのロックファイルの場所から自動で決まり、構成によっては turbopack.root で指定します。webpack の resolve.symlinks(既定 true)と Vite の resolve.preserveSymlinks(既定 false)も、npm link やシンボリックリンクを使う構成で解決結果に関わる設定です。
Next.js の Module not found(App Router・'use client'・Turbopack)
この節では、Next.js で出る Module not found: Can't resolve の文言と、Next.js ならではの原因・直し方が分かります。
Next.js 16.4.5 で next build --webpack を実行したときの原文です。webpack 単体より短く、探した場所の記録は出ません。代わりに公式の説明ページの URL が付きます。
Failed to compile.
./app/page.js
Module not found: Can't resolve '../components/header'
https://nextjs.org/docs/messages/module-not-found
> Build failed because of webpack errors
開発サーバー(next dev --webpack)では、ページを開いたときにターミナルへ同じ文言が出て、ページの応答は HTTP 500 になりました。
○ Compiling /page ...
⨯ ./app/page.js
Module not found: Can't resolve '../components/header'
https://nextjs.org/docs/messages/module-not-found
Next.js の公式ページ(Module Not Found)が挙げている原因は、依存関係に入っていない・別のフォルダーにある・大文字小文字が違う・Node.js 専用のモジュールを使っている、の4つです。App Router でいちばん迷いやすいのは4つ目で、'use client' を書いたファイル(クライアントコンポーネント)で fs を import すると Can't resolve 'fs' になり、'use client' を外してサーバーコンポーネントにすると同じコードが通りました。
// components/Reader.js
// 'use client'; ← これがあると Module not found: Can't resolve 'fs'
import fs from 'fs';
export default function Reader() {
return <p>{typeof fs.readFileSync}</p>;
}
'use client' を外したあとのビルドは成功し、静的に生成された HTML には <p>function</p> が入っていました。サーバー側で fs が動いたということです。ボタンのクリックなどでブラウザ側の機能が要る場合は、ファイルを読む部分をサーバーコンポーネントに残し、結果を props でクライアントコンポーネントへ渡す形に分けます。
Next.js 16 の既定のバンドラーは Turbopack です(公式ドキュメント)。webpack 用に書いた resolve.alias や resolve.fallback は Turbopack には効かず、公式ドキュメントでは turbopack.resolveAlias を使い、ブラウザ向けだけ差し替える { browser: '…' } という条件付きの書き方が案内されています。
// next.config.js(Turbopack。公式ドキュメントの例をもとにした形)
module.exports = {
turbopack: {
resolveAlias: {
underscore: 'lodash',
mocha: { browser: 'mocha/browser-entry.js' },
},
},
};
App Router の基本とビルド結果の読み方は、関連記事「Next.js App Router 入門|v16対応・実際のビルド結果つき」で扱っています。
Vite の Failed to resolve import(開発サーバーとビルドの違い)
この節では、Vite で出る Failed to resolve import の原文と、開発サーバーとビルドで文言が変わる点、直し方が分かります。
Vite の Failed to resolve import は、webpack の Can't resolve と同じ「import を解決できない」エラーです。ただし Vite 8 は、開発サーバーとビルド(Rolldown)で別々の文言を出します。開発サーバーでは、ブラウザがそのモジュールを要求したときに、ターミナルへ次のように出ました。
[vite] Internal server error: Failed to resolve import "./components/header" from "src/main.js". Does the file exist?
Plugin: vite:import-analysis
File: /app/src/main.js:1:20
1 | import Header from './components/header'; console.log(Header);
| ^
2 |
このとき、curl で /src/main.js を要求すると HTTP 500 が返り、本文はエラーを表示するための HTML でした。vite build では、相対パスとパッケージ名で文言が分かれました。
[UNRESOLVED_IMPORT] Could not resolve './components/header' in src/main.js
╭─[ src/main.js:1:20 ]
│
1 │ import Header from './components/header'; console.log(Header);
│ ──────────┬──────────
│ ╰──────────── Module not found.
│
│ Help: 'src/main.js' is imported by the following path:
│ - src/main.js
│ - index.html
───╯
Error: [vite]: Rolldown failed to resolve import "dayjs" from "/app/src/main.js".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rolldownOptions.external`
2つ目の文言にある build.rolldownOptions.external は、CDN から読み込むなどの理由で「わざとまとめに含めない」ときの設定です。単にインストールし忘れた場合に external へ足すと、ビルドは通っても実行時に読み込めなくなります。文言の提案に従う前に、まず原因1〜5のどれかを確かめます。dayjs をインストールして @/ を resolve.alias で設定し直すと、✓ built in 42ms でビルドが通りました。
開発サーバーでは動くのにビルドで失敗する場合、または逆の場合は、大文字小文字(原因3)と、tsconfigPaths が効く範囲(原因5の allowJs)を疑います。vite.config の書き方全般は、関連記事「vite.configの書き方|用途別コピペ一覧とVite 8の変更点」で扱っています。
どのツールも失敗はすぐに返ってくるので、直してはビルドする、を小さく何度も回すのが近道です。Next.js の next build --webpack は、この環境(wasm 版の SWC)ではエラーで止まるまで約7秒、成功したときは「Compiled successfully in 16.8s」でした。ネイティブの SWC ではもっと短くなります。
OS・環境別の注意(Windows・Mac・Linux・CI・Docker)
この節では、同じコードでも OS や実行環境によって Can't resolve が出たり出なかったりする理由と、環境ごとに見るところが分かります。
| 環境 | 起こりやすいこと | 見るところ |
|---|---|---|
| Windows | 大文字小文字の違いが手元では通る。パスの区切りに \ を書いてしまう | import は常に / で書く。git mv で名前を変える |
| Mac | 大文字小文字の違いが手元では通る(Vite の公式ドキュメントも Windows・macOS を区別しない環境として挙げている) | CI で失敗したらまず大文字小文字 |
| Linux | 大文字小文字を区別するので、違いがそのままエラーになる | webpack の「differs only in casing」 |
| CI(GitHub Actions など) | node_modules が無い状態から始まる。.gitignore で必要なファイルが入っていない | npm ci の実行と、import 先がリポジトリにあるか |
| Docker | COPY の順番で node_modules やソースが入っていない。手元の node_modules を上書きコピー | .dockerignore と、コンテナの中で npm ci |
Windows で import に '.\components\Header' と書くと、文字列の中の \ はエスケープの記号として扱われ、意図しないパスになります。Node.js で確かめると、この文字列は .componentsHeader になりました。JavaScript の import は OS に関係なく / で書きます。Vite の公式ドキュメントには、Windows でドライブをまたぐリンク(別のドライブへのシンボリックリンク)があると Vite が動かない場合がある、という項目もあります。
CI だけで失敗するときは、手元でも CI と同じ条件を作ると原因が見えます。node_modules を消して npm ci から始める、または Linux のコンテナの中でビルドする、のどちらかで再現できることが多いです。
よくあるエラー・つまずきと判断表
この節では、Module not found: Can't resolve の周辺でよく出る文言の意味と直し方、どの直し方を選ぶかの判断が表で分かります。
よくあるエラー・つまずき(原文つき)
| 症状・原文 | 原因 | 直し方 |
|---|---|---|
| Can't resolve 'dayjs' | 未インストール | npm install dayjs |
| Did you mean './components/Header.js'? … differs from the request only in casing | 大文字小文字 | import をファイル名に合わせる |
| Requests that should resolve in the current directory need to start with './' | ./ の付け忘れ | './components/Header' と書く |
| BREAKING CHANGE: … resolved as fully specified | "type": "module" で拡張子が必須 | 拡張子を書く/fullySpecified: false |
| node_modules/@/components doesn't exist | エイリアスがバンドラーに無い | resolve.alias・tsconfigPaths・paths |
| BREAKING CHANGE: webpack < 5 used to include polyfills | path などをブラウザで使った | サーバー側へ移す/resolve.fallback |
| Module "fs" has been externalized for browser compatibility | Vite で fs をブラウザで使った | ファイルを読む処理をサーバー側へ |
| is not exported under the conditions | exports に無いパス | 公開されたパスで import |
| use ./dist/index.js from main … doesn't exist | 依存先のパッケージが未ビルド | 依存先をビルドする |
| ビルドは通ったが実行時に Cannot find module | webpack のエラーを見落とした | ビルドの終了コードで CI を止める |
判断表:どの直し方を選ぶか
同じエラーにも直し方が複数あります。迷ったら上から順に当てはめます。
- 1import の文字列が間違っている → import を直す綴り・階層・大文字小文字・./ の付け忘れ。設定より先に直す
- 2パッケージが入っていない → npm install(CI は npm ci)package.json に残す。グローバルには入れない
- 3チームで決めた書き方(@/ など)→ バンドラーの設定を足すTypeScript とバンドラーの両方にそろえる
- 4fs など Node.js 専用 → 処理をサーバー側へ移すブラウザで使わないと分かっているときだけ fallback: false
- 5パッケージの内部パス → 公開されたパスに変えるexports を無理に回り込まない
- 6わざとまとめに含めない → externalCDN などで別に読み込むと決めたときだけ
| 状況 | 選ぶ直し方 | 選ばないほうがよい直し方 |
|---|---|---|
| 拡張子 .jsx が見つからない | extensions: ['.jsx', '...'] | '...' なしで一覧を置き換える |
| "type": "module" で拡張子エラー | import に .js を書く | 全ファイルの fullySpecified を外したままにする |
| Vite で @/ が解決できない | resolve.alias か tsconfigPaths(allowJs も確認) | tsconfig の paths だけ書いて終える |
| ライブラリが path を少し使う | resolve.fallback に path-browserify か false | webpack を前の版に戻す |
| CI だけで失敗 | 大文字小文字を直し、npm ci で再現 | CI の OS を Windows・Mac に変える |
よくある質問
この節では、Module not found: Can't resolve について、よく調べられている疑問への短い答えが分かります。
Q. Module not found: Can't resolve と Cannot find module は何が違いますか?
Can't resolve は webpack などのバンドラーがビルドのときに出すエラー、Cannot find module は Node.js がプログラムを実行するときに出すエラーです。原因(未インストール・パスの間違い)は似ていますが、出る場面が違います。webpack のエラーを見落として出力したファイルを動かすと、実行時に Cannot find module になります。
Q. npm install したのに Can't resolve が消えません。
別のフォルダーでインストールしていないか、package.json と同じ場所で実行したかを見ます。次に、開発サーバーを止めて起動し直し、node_modules/.vite・.next・node_modules/.cache を消します。それでも残るなら、引用符の中身が本当にパッケージ名か(大文字小文字・綴り)を見直します。
Q. 手元では動くのに、Vercel や GitHub Actions のビルドだけ失敗します。
まず大文字小文字の違いを疑います。Windows・Mac は区別せず、Linux は区別するためです。webpack なら「differs from the request only in casing」と出ます。ほかに、.gitignore で import 先のファイルがリポジトリに入っていない場合もあります。
Q. VS Code では赤線が出ないのに、ビルドで @/ が解決できません。
VS Code の補完は tsconfig.json の paths を読みますが、webpack は読みません。webpack なら resolve.alias、Vite なら resolve.alias か resolve.tsconfigPaths に同じ対応を書きます。Next.js は paths を組み込みで読みます。
Q. Can't resolve 'fs' はポリフィルを入れれば直りますか?
ビルドのエラーは消せますが、ブラウザで利用者のファイルを読めるようにはなりません。ファイルを読む処理は API やサーバーコンポーネントへ移すのが基本です。ライブラリが使っていないと分かっているときだけ resolve.fallback: { fs: false } にします。
Q. Vite の Failed to resolve import と webpack の Can't resolve は別のエラーですか?
同じ「import を解決できない」エラーで、ツールごとに文言が違うだけです。原因の調べ方も同じです。Vite 8 では、ビルドのときは「Rolldown failed to resolve import」や「[UNRESOLVED_IMPORT] Could not resolve」という文言になります。
Q. CSS や画像の import で Can't resolve が出ます。
まずファイル名とパスを確かめます。この環境の webpack 5.112.2 では、loader を設定しなくても .css と .png の import がビルドできましたが、前の版の webpack では css-loader などの設定が要る構成もあります。Vite は CSS と画像を標準で扱います。存在しない CSS を import すると、JavaScript と同じ Can't resolve './nothere.css' になりました。
Q. エラーの下に続く長い doesn't exist の行は読む必要がありますか?
原因がすぐに分からないときに役立ちます。どのフォルダーの node_modules を探したか、どの拡張子を試したか、package.json のどのフィールド(main や exports)を使ったかが書かれています。モノレポの未ビルドは、この部分に「use ./dist/index.js from main」と出て分かりました。
Q. 以前は動いていたのに、パッケージを更新したら Can't resolve が出ました。
更新でパッケージの package.json に exports が追加され、内部のファイルを直接 import できなくなった可能性があります。「is not exported」と出ていれば当てはまります。README で案内されている import のしかたに合わせます。
Q. Next.js で webpack の resolve.alias を書いたのに効きません。
Next.js 16 の既定のバンドラーは Turbopack で、webpack 用の設定は使われません。Turbopack では next.config の turbopack.resolveAlias に書きます。@/ のようなパスのエイリアスは、tsconfig.json か jsconfig.json の paths に書けば Turbopack・webpack のどちらでも読まれます。
まとめ
この節では、記事の要点を5つにまとめて確認できます。
- Module not found: Can't resolve 'X' は、import に書いた X をファイルに結び付けられないというビルドのエラーです。引用符の中身の書き出しで原因の候補が絞れます。
- パッケージ名なら
npm lsで確かめてnpm install。グローバルに入れても直りません。 - 自分のファイルなら、相対パスの基準(import を書いたファイルの場所)、大文字小文字、拡張子を見ます。Windows・Mac で動いて Linux・CI で失敗するなら、まず大文字小文字です。
@/は TypeScript だけでなくバンドラーにも設定します。Vite 8 の tsconfigPaths は、.js ファイルでは allowJs が無いと効きませんでした。- fs など Node.js 専用のモジュールは、ブラウザで動くコードから外してサーバー側へ移すのが基本です。exports やモノレポの未ビルドは、エラーの下に続く探索の記録に理由が出ます。
参考・出典
確認日はいずれも 2026年11月5日です。
- webpack「Resolve」(resolve.alias・extensions・fallback・fullySpecified・symlinks・preferRelative):https://webpack.js.org/configuration/resolve/
- Vite「Troubleshooting」(Module externalized for browser compatibility・大文字小文字):https://vite.dev/guide/troubleshooting.html
- Vite「Shared Options」(resolve.alias・resolve.extensions・resolve.tsconfigPaths・resolve.preserveSymlinks):https://vite.dev/config/shared-options.html
- Next.js「Module Not Found」:https://nextjs.org/docs/messages/module-not-found
- Next.js「Installation」(Absolute Imports and Module Path Aliases・Turbopack が既定であること):https://nextjs.org/docs/app/getting-started/installation
- Next.js「turbopack」(resolveAlias・resolveExtensions・root):https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack
- Node.js「Modules: Packages」(exports フィールドと ERR_PACKAGE_PATH_NOT_EXPORTED):https://nodejs.org/api/packages.html
- npm Docs「Workspaces」:https://docs.npmjs.com/cli/v12/using-npm/workspaces/
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Module not found: Can't resolveの原因8つと直し方」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。