株式会社renue
AI導入・DXの悩みをプロに相談してみませんか？
AIやDXに関する悩みがありましたら、お気軽にrenueの無料相談をご利用ください。 renueのAI支援実績、コンサルティングの方針や進め方をご紹介します。
「難しい方に目が行くが、一番最初に『再起動しろ』と書いてある」
エラーメッセージが表示されたとき、多くのエンジニアは長いスタックトレースやコマンドの複雑そうな部分に目が行きます。しかし、あるチームのガイドラインにはこう書かれています。「すぐにコマンドの難しそうな方に目が行くが、『再起動しろ』って一番最初に言っている。そして原因はそのまんま再起動していないことだった」
まず簡単な方から試す——これがエラーメッセージ読解の最も重要な原則です。本記事では、エラーメッセージを体系的に読み解く技術を、AI時代のデバッグ手法と合わせて解説します。
エラーメッセージ読解の3ステップ
ステップ1：最初の1行を読む
エラーメッセージの最初の1行に最も重要な情報が含まれています。スタックトレースの深い部分や技術的な詳細に飛びつく前に、まず1行目の指示に従います。
Error: ENOSPC: no space left on device → ディスク容量不足。ログやイメージを削除すれば解決。 Error: Module not found: Can't resolve 'xxx' → パッケージが未インストール。npm installで解決。 Error: ECONNREFUSED 127.0.0.1:3306 → MySQLが起動していない。コンテナの状態を確認。
ステップ2：エラーの種類を分類する
| エラー種別 | 特徴 | 典型的な原因 | まず試すこと |
|---|---|---|---|
| 接続エラー | ECONNREFUSED, timeout, DNS | サービス未起動、ネットワーク設定 | 対象サービスの起動確認 |
| 権限エラー | 403 Forbidden, Permission denied | 認証トークン切れ、ロール不足 | トークン再取得・権限確認 |
| リソースエラー | ENOSPC, OOM, quota exceeded | ディスク・メモリ・API枠の枯渇 | 不要リソースの削除 |
| 依存エラー | Module not found, version mismatch | パッケージ未インストール・バージョン不一致 | npm install / lockfile更新 |
| 型・スキーマエラー | TypeError, table does not exist | コードとDB/APIの不整合 | マイグレーション実行・型定義確認 |
ステップ3：AIに正しく伝える
エラーメッセージをAIに貼り付ける際は、完全な情報を提供します。部分的な情報では部分的な回答しか得られません。
AIに提供すべき5つの情報
- 完全なエラーメッセージ（省略しない）
- 完全なスタックトレース（長くても全文）
- 該当コード（エラーが発生した箇所）
- 言語・フレームワークのバージョン
- 期待した動作と実際の動作
「難しい方に行く」バイアスを克服する
エンジニアには「複雑な原因を探したがる」バイアスがあります。しかし、実際の障害の大半はシンプルな原因です。
よくある「シンプルな原因」ランキング
- サービスが起動していない（docker compose up忘れ）
- 環境変数が設定されていない（.envファイル未作成）
- パッケージがインストールされていない（npm install忘れ）
- ポートが使用中（前回のプロセスが残っている）
- ブランチが違う（mainのまま開発ブランチの機能を探している）
- キャッシュが古い（ブラウザキャッシュ、.nextディレクトリ）
- 再起動していない（設定変更後にサーバーを再起動していない）
このリストを上から順にチェックするだけで、8割のエラーは解決します。
環境変数トラブルの体系的対処
環境変数は最も頻繁にトラブルの原因になる領域です。
環境変数が反映されない3大原因
| 原因 | メカニズム | 対策 |
|---|---|---|
| 読み込みタイミング | プロセス起動時に読み込まれるため、変更後に再起動が必要 | 設定変更後は必ずサービス再起動 |
| 末尾スラッシュ | パスの末尾に/があるかないかでstartsWith比較が失敗 | パス定義を統一（末尾スラッシュなし） |
| 親シェルの継承 | .zshrcを変更しても、既存のターミナルは古い値を保持 | 新しいターミナルを開くか、source ~/.zshrc |
実例：MCP書き込み権限エラー
Error: Write path not allowed: /api/renue/daily-reports
この実例では3つの原因が重なっていました。
- 設定が未追加：新しいエンドポイントが許可リストに追加されていなかった
- 末尾スラッシュの不一致：許可リストが
/api/renue/daily-reports/（スラッシュあり）で、実際のパスが/api/renue/daily-reports（スラッシュなし） - 再起動で治らない：親シェルの古い環境変数を毎回継承するため
Docker起動失敗の診断フローチャート
コンテナが起動しない
├ docker compose ps → Exitedの場合
│ └ docker compose logs → エラーメッセージ確認
│ ├ "no space left" → docker image pruneでディスク確保
│ ├ "port already in use" → lsof -i :ポート番号で競合プロセス確認
│ └ "database connection refused" → DBコンテナの起動確認
│
├ docker compose ps → Upだが機能しない場合
│ └ ヘルスチェック通過だが画面エラー
│ ├ "table does not exist" → マイグレーション未実行
│ └ "NXDOMAIN" → DNS設定ミス（プライベートDNSゾーン未リンク等）
│
└ docker compose up自体がエラー
├ "image not found" → docker loginの認証切れ
└ "no matching manifest for linux/amd64" → ビルド時に--platform未指定
AI時代のエラー読解：AIは人間より上手い
2026年現在、AIはスタックトレースの読解において多くの人間より優秀です。AIはフラストレーションを感じず、思い込みをせず、体系的にチェックするからです。
AIが特に強い領域
- スタックトレースの根本原因特定：複数フレームにまたがる原因を追跡
- エラーメッセージの平易な説明：技術用語を人間が理解できる言葉に翻訳
- 類似エラーの過去事例検索：大量のコードベースから類似パターンを発見
- 修正候補の提案：原因に基づく具体的な修正コードの生成
ただしAIの限界を知る
- AIの修正提案は「仮説」：対照実験で検証するまで確定ではない
- 環境固有の問題はAIに伝えないとわからない：「VMの閉域環境で動かしている」「Apple SiliconでLinux向けにビルドしている」等のコンテキスト
- 表面的な修正に留まるリスク：「結果論じゃなくて事実ベースで調べて」と明示的に要求する
非エンジニアのためのエラー報告ガイド
非エンジニアが勝手な類推をせず、ありのままの事実を伝えることが重要です。「データベースの問題だと思います」ではなく、「この画面でこのボタンを押したらこのエラーが出ました」と報告します。
エラー報告テンプレート
■いつ：2026年4月10日 15:00頃 ■どこで：○○画面の△△ボタン ■何をしたら：□□を入力して確定を押した ■何が起きた：画面が真っ白になった ■エラーメッセージ：（画面に表示されたテキストをそのままコピー） ■再現する？：もう一度やったら同じことが起きた
まとめ：エラーメッセージ読解チェックリスト
| ステップ | チェック |
|---|---|
| 1. 最初の1行 | エラーメッセージの1行目を読んだか |
| 2. シンプル原因 | 7つの「よくある原因」を上から順にチェックしたか |
| 3. 分類 | 接続/権限/リソース/依存/型のどれか特定したか |
| 4. 環境変数 | 読み込みタイミング/末尾スラッシュ/親シェル継承を確認したか |
| 5. AI活用 | 完全なエラー+スタック+コード+バージョン+期待動作をAIに提供したか |
| 6. 検証 | AIの修正提案を対照実験で検証したか |
エラーメッセージは「敵」ではなく「ヒント」です。まず簡単な方から試し、1行目の指示に素直に従い、シンプルな原因を排除してから複雑な調査に入る。この順序を守るだけで、エラー対応の速度と精度は劇的に向上します。
関連記事
開発プロセスの改善はrenueにご相談ください。
