エラーが出た！── バイブコーディングで困ったときの対処法

エラーは「普通」のこと

バイブコーディングをしていると、必ずエラーに遭遇する。AIが完璧なコードを書くわけではないし、環境の違いで動かないこともある。

大事なのは「エラー＝失敗」ではないということ。 エラーは「ここを直せば動くよ」というヒントだ。

プロのエンジニアでも、コードが一発で完璧に動くことはほとんどない。実際、開発作業の30〜50%はデバッグ（エラーの修正）に費やされると言われている。エラーを恐れる必要はまったくない。

ℹ️

バイブコーディングの強み

従来のプログラミングではエラーメッセージを自力で解読する必要があった。バイブコーディングなら、エラーをAIに貼り付けるだけで解決してくれる。エラー対応のハードルは劇的に下がっている。

トラブルシューティングの流れ

エラーに遭遇したとき、闇雲に対処するのではなく、順序立てて対応すると効率がいい。以下のフローに沿って進めよう。

Step 1

エラーメッセージを確認する

ターミナルやブラウザの開発者ツール（Console）にエラーが表示されていないか確認。赤い文字やERROR表記を探す。

30秒

Step 2

エラーメッセージを全文コピーする

一部ではなく全文をコピー。スタックトレース（at xxx...の部分）も含めて全部コピーするのがコツ。

10秒

Step 3

AIにエラーを貼り付けて修正依頼

後述のテンプレートを使い、状況・エラー・環境情報をセットでAIに伝える。

1〜3分

Step 4

AIの提案を適用して動作確認

修正コードを適用し、npm run devなどで再度確認。直らなければStep 3に戻る。

1〜5分

Step 5

直ったら即コミット

git add . → git commit -m '修正内容' で変更を保存。次のエラーに備える。

30秒

💡

「3回試してダメなら別のアプローチ」

同じ方法でAIに3回聞いても解決しない場合は、アプローチを変えよう。エラーの原因が想定と違う可能性がある。「別の方法で実装してください」と指示するのも有効だ。

よくあるエラー15パターンと解決法

バイブコーディングで遭遇しやすいエラーを、カテゴリごとに整理した。それぞれ「原因」「解決法」「AIへの指示例」をセットで紹介する。

npm関連のエラー（4パターン）

1. `npm install` が失敗する

項目	内容
エラー例	`npm ERR! code ERESOLVE` / `npm ERR! peer dep`
原因	パッケージ同士のバージョンが競合している
解決法	`npm install --legacy-peer-deps` を試す
AIへの指示例	「npm installで以下のエラーが出ます。依存関係を解決してください：[エラー全文]」

2. `npm install` で権限エラー

項目	内容
エラー例	`EACCES: permission denied` / `Error: EPERM`
原因	Mac: グローバルインストール権限不足 / Windows: 管理者権限不足
解決法	Mac: `sudo npm install -g xxx` / Windows: ターミナルを管理者として実行
AIへの指示例	「npm installで権限エラーが出ます。OSはMacです：[エラー全文]」

⚠️

sudoの多用は避ける

sudo npm install（sudo付きのローカルインストール）は権限を壊す原因になる。sudoが必要なのはグローバルインストール（-g）のときだけ。ローカルインストールでsudoが必要になる場合は、node_modulesの所有者を修正しよう。

3. Node.jsのバージョンが合わない

項目	内容
エラー例	`The engine "node" is incompatible with this module`
原因	プロジェクトが要求するNode.jsバージョンと、PCにインストールされているバージョンが違う
解決法	`node --version`で確認 → nvm（Mac）やnvm-windows（Windows）でバージョンを変更
AIへの指示例	「Node.jsのバージョンエラーが出ます。現在v16です。更新方法を教えてください」

4. `package.json` が壊れた・見つからない

項目	内容
エラー例	`npm ERR! enoent ENOENT: no such file or directory, open 'package.json'`
原因	プロジェクトのルートフォルダにいない、またはpackage.jsonが削除された
解決法	`cd`でプロジェクトフォルダに移動。削除した場合はgitで復元
AIへの指示例	「package.jsonが見つからないエラーが出ます。現在のディレクトリは[パス]です」

ビルド・開発サーバーのエラー（4パターン）

5. `npm run dev` でポートが使用中

項目	内容
エラー例	`Error: listen EADDRINUSE: address already in use :::3000`
原因	別のターミナルで既にサーバーが起動している
解決法	別のターミナルを閉じる、またはポート番号を変更して起動
AIへの指示例	「ポート3000が使用中のエラーが出ます。プロセスを終了する方法を教えてください」

ポートを使っているプロセスを強制終了するコマンド：

# Mac
lsof -i :3000
kill -9 [PID番号]

# Windows
netstat -ano | findstr :3000
taskkill /PID [PID番号] /F

6. 構文エラー（SyntaxError）

項目	内容
エラー例	`SyntaxError: Unexpected token` / `Unterminated string literal`
原因	括弧の閉じ忘れ、カンマの抜け、クォートの不一致など
解決法	エラーメッセージに表示されるファイル名と行番号をAIに伝える
AIへの指示例	「src/App.jsxの42行目でSyntaxErrorが出ています。ファイルの内容を確認して修正してください」

7. モジュールが見つからない（Module not found）

項目	内容
エラー例	`Module not found: Can't resolve 'xxx'` / `Cannot find module 'xxx'`
原因	パッケージ未インストール、importパスの間違い、ファイル名のtypo
解決法	パッケージ名を確認して`npm install xxx`。パスの間違いならAIに修正依頼
AIへの指示例	「‘react-router-dom’が見つからないエラーです。インストールと正しい使い方を教えてください」

8. TypeScriptの型エラー

項目	内容
エラー例	`Type 'string' is not assignable to type 'number'`
原因	TypeScriptの型定義と実際のデータが一致しない
解決法	エラーメッセージをAIに貼る。バイブコーディングでは型の詳細を理解する必要はない
AIへの指示例	「TypeScriptの型エラーが出ています。修正してください：[エラー全文]」

ℹ️

TypeScriptのエラーが多すぎる場合

バイブコーディング初心者でTypeScriptのエラーに苦しむ場合、プロジェクトをJavaScriptに切り替えるのも手。AIに「このプロジェクトをTypeScriptからJavaScriptに変換してください」と指示すれば対応してくれる。

ランタイムエラー（画面上のエラー）（4パターン）

9. 画面が真っ白になる

項目	内容
エラー例	ブラウザに何も表示されない（白い画面のまま）
原因	JavaScriptのエラーでレンダリングが止まっている
解決法	ブラウザの開発者ツール（F12 → Console）を開いてエラーを確認
AIへの指示例	「画面が真っ白です。ブラウザのConsoleに以下のエラーが出ています：[エラー全文]」

ブラウザの開発者ツールの開き方：

ブラウザ	ショートカット
Chrome	`F12` または `Ctrl+Shift+I`（Mac: `Cmd+Option+I`）
Safari	`Cmd+Option+I`（事前に開発メニューを有効化）
Firefox	`F12` または `Ctrl+Shift+I`

10. 「Cannot read properties of undefined」

項目	内容
エラー例	`TypeError: Cannot read properties of undefined (reading 'map')`
原因	データがまだ読み込まれていない状態でアクセスしている
解決法	データの存在チェック（オプショナルチェーン `?.`）を追加
AIへの指示例	「undefinedのプロパティを読み取れないエラーが出ます。データの読み込み待ちを適切に処理してください」

11. CORS（クロスオリジン）エラー

項目	内容
エラー例	`Access to fetch at 'xxx' has been blocked by CORS policy`
原因	外部APIへのリクエストがブラウザのセキュリティ制限でブロックされている
解決法	サーバーサイドでAPIを呼ぶ（API Routeを作る）、またはプロキシ設定を追加
AIへの指示例	「CORSエラーが出ています。サーバーサイドでAPIを呼ぶように変更してください：[エラー全文]」

12. APIキーが無効・期限切れ

項目	内容
エラー例	`401 Unauthorized` / `403 Forbidden` / `Invalid API key`
原因	APIキーが間違っている、期限切れ、無料枠の上限超過
解決法	APIの管理画面でキーを確認・再発行。環境変数（.env）に正しく設定
AIへの指示例	「APIから401エラーが返ってきます。APIキーは.envファイルに設定済みです。原因を調べてください」

⚠️

APIキーの取り扱い注意

APIキーは絶対にコードに直接書かない。必ず.envファイルに入れ、.gitignoreに.envを追加しておくこと。GitHubにAPIキーをプッシュすると、悪用される危険がある。

デプロイ・公開時のエラー（3パターン）

13. ビルドがCloudflare/Vercelで失敗する

項目	内容
エラー例	`Build failed` / `Command "npm run build" exited with 1`
原因	ローカルでは動くが本番ビルドでエラー。型エラーや未使用変数の警告がエラー扱いになることがある
解決法	ビルドログ全文をAIに貼る。ローカルで`npm run build`を先に実行して確認
AIへの指示例	「Cloudflare Pagesのビルドが失敗しました。ビルドログは以下です：[ログ全文]」

14. デプロイ後に画面が404

項目	内容
エラー例	ページにアクセスすると `404 Not Found`
原因	ルーティング設定の問題、ビルド出力先の設定ミス、ベースパスの設定漏れ
解決法	デプロイ先の設定（ビルド出力ディレクトリ）を確認
AIへの指示例	「Cloudflare Pagesにデプロイしましたが、トップページ以外が404になります。SPAのルーティング設定を教えてください」

15. 環境変数がデプロイ先で読み込めない

項目	内容
エラー例	ローカルでは動くが、デプロイ後にAPI連携が動かない
原因	`.env`ファイルはデプロイ先にアップロードされない。デプロイサービスの管理画面で設定が必要
解決法	Cloudflare/Vercelの管理画面 → Settings → Environment Variables で追加
AIへの指示例	「デプロイ後にAPIが動きません。環境変数の設定方法を教えてください。デプロイ先はCloudflare Pagesです」

環境別トラブルシューティング

MacとWindowsでは、同じ操作でも異なるエラーが発生することがある。ここでは環境固有のよくある問題をまとめた。

Mac固有の問題

問題	原因	解決法
`command not found: node`	Node.jsがインストールされていない、またはPATHが通っていない	Homebrewで再インストール: `brew install node`
`xcrun: error: invalid active developer path`	Xcode Command Line Toolsが未インストール	`xcode-select --install` を実行
ファイルパスの大文字小文字	Macはデフォルトで大文字小文字を区別しない	import文のファイル名が本番環境（Linux）と一致するか確認
`.DS_Store`が邪魔	Finderが自動生成するファイル	`.gitignore`に`.DS_Store`を追加

Windows固有の問題

問題	原因	解決法
`'node' is not recognized`	環境変数PATHにNode.jsが追加されていない	Node.jsを公式サイトから再インストール（PATHに追加するオプションをON）
パスが長すぎるエラー	Windowsのパス文字数制限（260文字）	プロジェクトをCドライブ直下（`C:\projects\`）に作成
改行コードの問題	WindowsはCRLF、Mac/LinuxはLF	`.gitattributes`で改行コードを統一
PowerShellの実行ポリシー	スクリプト実行がブロックされる	`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` を実行
`EPERM: operation not permitted`	ファイルがロックされている（エディタやウイルス対策ソフト）	エディタを閉じる、ウイルス対策の除外設定にフォルダを追加

💡

WindowsユーザーにはWSL2もおすすめ

Windows上でLinux環境を使えるWSL2（Windows Subsystem for Linux）を導入すると、Mac/Linuxと同じコマンドが使え、環境差異によるトラブルが激減する。AIに「WSL2のセットアップ方法を教えてください」と聞いてみよう。

AIへのエラー報告テンプレート集

エラーの種類に応じて、AIへの伝え方を使い分けると解決が早い。

基本テンプレート（万能型）

【状況】
何をしようとしたか：[やったこと]
期待する動作：[どう動いてほしいか]
実際の動作：[何が起きたか]

【エラーメッセージ】
[エラーの全文をここに貼る]

【環境】
OS：Mac / Windows
Node.js：v22.x.x（node --versionで確認）
ツール：Claude Code / Cursor / Bolt
フレームワーク：Next.js / Astro / React等

ビルドエラー用テンプレート

【状況】
npm run buildでビルドエラーが発生しました。
npm run devでは正常に動作しています。

【ビルドログ】
[ビルドログの全文]

【直前に変更したファイル】
- [ファイル名1]
- [ファイル名2]

デザイン崩れ用テンプレート

【状況】
[ページ名]のレイアウトが崩れています。

【期待する表示】
- PCで3カラム表示
- スマホで1カラム表示

【実際の表示】
- PCでは正常
- スマホで要素が重なっている

【ブラウザ】Chrome / Safari / Firefox
【画面幅】[ピクセル数、わかれば]

API連携エラー用テンプレート

【状況】
[API名]との連携でエラーが発生しています。

【エラーレスポンス】
ステータスコード：[401/403/500等]
レスポンスボディ：[エラー内容]

【リクエスト内容】
エンドポイント：[URL]
メソッド：GET / POST
ヘッダー：Authorization設定済み

【環境変数】
.envに以下を設定済み（値は伏せます）：
API_KEY=設定済み
API_URL=https://...

⚠️

APIキーの値はAIに送らない

テンプレートの「環境変数」の部分で、APIキーの実際の値をAIに送らないように注意。「設定済み」とだけ伝えれば十分だ。Claude CodeなどローカルAIツールの場合は.envを直接読めるので、値を貼る必要はない。

それでも解決しない場合のエスカレーションパス

AIに何度聞いても解決しないケースもある。そんなときの段階的な対処法を紹介する。

レベル1: 基本リセット（所要時間 1〜2分）

まずは環境をリフレッシュする。これだけで直ることが意外と多い。

ターミナルを閉じて開き直す — 環境変数のキャッシュが原因のケース
ブラウザのキャッシュをクリア — Ctrl+Shift+R（Mac: Cmd+Shift+R）でスーパーリロード
開発サーバーを再起動 — Ctrl+Cで停止 → npm run devで再起動

レベル2: 依存関係のリセット（所要時間 2〜5分）

node_modulesを丸ごと入れ直す。依存関係の不整合が原因のエラーに有効。

# node_modulesとロックファイルを削除
rm -rf node_modules package-lock.json

# 再インストール
npm install

# 開発サーバーを起動
npm run dev

レベル3: キャッシュの完全クリア（所要時間 3〜5分）

フレームワークのキャッシュが壊れている場合に試す。

# Next.jsの場合
rm -rf .next node_modules package-lock.json
npm install
npm run dev

# Astroの場合
rm -rf dist .astro node_modules package-lock.json
npm install
npm run dev

# Viteベースの場合
rm -rf dist node_modules .vite package-lock.json
npm install
npm run dev

レベル4: Gitで前の状態に戻す（所要時間 1分）

直前のコミット時点まで戻す。「前は動いていた」ケースで最も確実。

# 変更を全て破棄して直前のコミットに戻す
git checkout .

# 特定のファイルだけ戻したい場合
git checkout -- src/App.jsx

⚠️

コミットしていない変更は消える

git checkout .はコミットしていない変更を全て削除する。実行前に、残したいコードがあればコピーしておこう。

レベル5: PCの再起動（所要時間 3〜5分）

古典的だが有効。メモリリーク、プロセスの残留、ファイルロックなど、ソフトウェアだけでは解決できない問題を一掃する。

レベル6: プロジェクトを作り直す（所要時間 10〜30分）

最終手段だが、バイブコーディング最大の強み。

同じプロンプト（指示）を使えば、AIは同じプロジェクトを再生成してくれる。修復に1時間かけるより、作り直した方が結果的に早いことがある。

新しいプロジェクトを作成してください。
要件は以下の通り：
[最初にAIに出した指示をここに貼る]

前回のプロジェクトで以下の問題がありました：
[発生した問題の説明]
今回は最初からこの問題を回避してください。

💡

プロンプトの保存がカギ

バイブコーディングでは、AIへの指示（プロンプト）がソースコードと同じくらい大事。良いプロンプトはテキストファイルに保存しておこう。作り直すときにそのまま使える。

レベル7: コミュニティに相談する

自力での解決が難しい場合、外部の知恵を借りる選択肢もある。

相談先	特徴	おすすめシーン
Stack Overflow	世界最大の技術Q&Aサイト	特定のエラーメッセージで検索
GitHub Issues	ライブラリの公式バグ報告	使っているライブラリの既知の問題
Discord / Slackコミュニティ	リアルタイムで相談	特定ツール（Cursor、Boltなど）のコミュニティ
X（Twitter）	エラーメッセージで検索	同じ問題に遭った人の解決法が見つかる

エラーを減らすための予防策

トラブルシューティングも大事だが、そもそもエラーを減らす習慣を身につけると、開発がスムーズになる。

こまめにコミットする

変更がうまく動くたびにgit commitする。これが最強の保険。

# 動作確認できたら即コミット
git add .
git commit -m "ヘッダーのナビゲーションを追加"

コミットの目安：

タイミング	例
機能を1つ追加したとき	「ログインフォームを実装」
デザインを調整したとき	「スマホ表示のレイアウト修正」
エラーを修正したとき	「APIの接続エラーを修正」
1日の作業終了時	「本日の作業分をコミット」

小さく作って確認する

一度に大量の指示を出すと、エラーが複合して原因特定が難しくなる。

1つの機能ごとにAIに指示 → 動作確認 → コミット
10個の機能を一気に作るのではなく、1つずつ積み上げる

`npm run build`をローカルで実行する

デプロイ前に必ずローカルでビルドを試す。デプロイ先で初めてビルドエラーに気づくのを防げる。

# ビルドを試す
npm run build

# ビルド結果をプレビュー（フレームワークによる）
npm run preview

エラーとの付き合い方

エラーが出たら：

慌てない — エラーは日常
メッセージを確認する（読めなくてもOK）
AIに丸投げ — エラー全文を貼る
直ったら即コミット — 次のエラーに備える
同じエラーに注目 — 繰り返すエラーはパターンとして覚える

プロのエンジニアもエラーの連続。違いは「エラーに慣れているかどうか」だけだ。バイブコーディングでは、AIがエラー解読を肩代わりしてくれるので、あなたがやるべきことは「正確に情報を伝えること」だけ。

よくある質問（FAQ）

Q1. エラーメッセージが英語で読めません。どうすればいい？

読めなくて問題ない。エラーメッセージはそのままAIに貼り付ければ、AIが日本語で原因と解決法を説明してくれる。翻訳する必要もない。むしろ英語のまま貼る方が、AIが正確に原因を判断できる。

Q2. AIに聞いても「同じ修正」を繰り返し提案されます

AIが問題の本質を捉えられていない可能性がある。以下を試そう：

コンテキストを増やす — エラーだけでなく、関連ファイルのコードも一緒に貼る
違う聞き方をする — 「別のアプローチで解決してください」と指示
新しい会話を始める — 長い会話はAIの文脈が混乱しがち。新しいチャットで最初から状況を説明する
別のAIツールに聞く — Claude CodeでダメならCursorで試す、など

Q3. `node_modules`フォルダが巨大すぎてストレージを圧迫しています

node_modulesはプロジェクトごとに数百MBになることがある。対処法：

使っていないプロジェクトのnode_modulesを削除（npm installでいつでも復元可能）
npx npkillコマンドで全プロジェクトのnode_modulesを一括管理・削除できる
node_modulesは.gitignoreに必ず入れる（Gitで管理しない）

Q4. ローカルでは動くのにデプロイすると動きません

最もよくある原因トップ3：

環境変数の未設定 — .envはデプロイ先にアップされない。管理画面で個別に設定が必要
大文字小文字の問題 — ローカル（Mac/Windows）は大文字小文字を区別しないが、デプロイ先（Linux）は区別する。import Header from './header'（小文字）なのにファイル名がHeader.jsx（大文字）だとエラーになる
Node.jsバージョンの違い — デプロイ先のNode.jsバージョンを確認し、ローカルと揃える

Q5. Gitで間違えてコミットしてしまいました。取り消せますか？

直前のコミットを取り消す（変更は残す）：

git reset --soft HEAD~1

これでコミットは取り消されるが、ファイルの変更はそのまま残る。安心して修正し直せる。

Q6. エラーが出ていないのに期待通りに動きません

エラーなしで動作がおかしいケースは、ロジックのバグ（プログラムの論理ミス）の可能性が高い。AIへの伝え方：

エラーは出ていませんが、期待通りに動きません。

【期待する動作】
ボタンをクリックしたらカウントが1増える

【実際の動作】
ボタンをクリックしても数字が変わらない

【関連コード】
[該当するコードを貼る]

「何が起きるべきか」と「実際に何が起きているか」の差分を具体的に伝えるのがポイント。

Q7. プロジェクトが複雑になるほどエラーが増えます。どうすれば？

これは自然な現象。コードが増えれば影響範囲が広がり、エラーも増える。対策：

機能ごとにブランチを分ける — git checkout -b feature/loginのように作業を分離
テストを書いてもらう — AIに「この機能のテストコードを書いてください」と指示
小さく分けて作業する — 1回のAI指示で変更するファイルは2〜3個まで
定期的にビルド確認 — npm run buildでエラーがないか頻繁にチェック