プログラミングのエラーは大きく 6 種類に分けられます。構文エラー、実行時エラー、参照エラー、ネットワークエラー、論理エラー、そして環境・設定エラーです。 分類の価値は用語を覚えることではなく、種類ごとに残る証拠が違う点にあります。種類が分かれば、バグ報告にどのメッセージ、どのリクエスト、どのスクリーンショットを添えるべきかが決まります。 本記事ではまずそのまま使える一覧表を示し、次にフロントエンドで最もよく見る 8 つのエラーを通して「同じエラーでも原因によって種類が変わる」ことを確認し、最後に実務的な話をします。1 つのエラーを、開発者が追加質問をせずに着手できる報告に変えるにはどうするか、という話です。
分類を独立した記事にする理由
多くのチームが困っているのはTypeError の意味ではありません。次の 3 つです。
- コンソールの赤い行をすべてバグと呼ぶ。実際には半分がサードパーティのスクリプトやブラウザ拡張由来です。
- 「ページが反応しない」をそのままバックエンドに渡す。実際にはフロントエンドがレスポンスの形を扱えていません。
- 「エラーが出ます」だけの報告を書き、開発者が「どのページ、どのブラウザ、何をクリックしたか」を 20 分かけて聞くことになる。
6 種類の一覧
| 種類 | 起きるタイミング | 典型的なメッセージ | 一次証拠の場所 |
|---|---|---|---|
| 構文エラー | コードを解析できず、スクリプト全体が止まる | Unexpected token、Unexpected end of input |
コンソールの最初の赤い行(以降は連鎖的な失敗が多い) |
| 実行時エラー | コードは動き、途中の処理で失敗する | TypeError、RangeError、Cannot read properties of undefined |
コンソール+きっかけとなった操作 |
| 参照エラー | 存在しない変数・フィールド・モジュールを使う | ReferenceError、x is not defined、undefined is not a function |
コンソール+ページ URL(どのルートが読み込めなかったか) |
| ネットワークエラー | リクエストの失敗、遮断、クロスオリジン、タイムアウト | 4xx / 5xx、blocked by CORS policy、net::ERR_ |
ネットワークパネル:URL、ステータスコード、レスポンスヘッダー |
| 論理エラー | エラーは出ないが結果が違う | 赤い表示がない | 操作手順、期待結果と実際の結果、データ例 |
| 環境・設定エラー | 特定の端末、環境、アカウントだけで起きる | 無関係な 404、真っ白な画面、静的ファイルが読めない | ブラウザと OS のバージョン、ビューポート、ビルド/環境の識別子、アカウント権限 |
構文・実行時・論理の境界は曖昧
同じメッセージでも、原因によって種類が変わります。文言では決まりません。Uncaught TypeError: Cannot read properties of undefined (reading 'map') は実行時エラーです。undefined に対して .map を呼んだ、という意味です。しかし原因は次のいずれかかもしれません。
- API のレスポンス構造が変わった(ネットワーク)
- 初期状態にデフォルト値がない(論理)
- 非同期リクエストが返る前に描画した(タイミング)
よく見るフロントエンドのエラー 8 つ
| # | メッセージ | 通常の意味 | 見る場所 |
|---|---|---|---|
| 1 | TypeError: Cannot read properties of undefined |
データが未到達、構造が不一致、オプショナルチェーンの漏れ | コンソール+該当リクエストのレスポンス |
| 2 | ReferenceError: x is not defined |
変数未宣言、スクリプトの読み込み順、バンドル漏れ | コンソール+ソース上のスクリプト順 |
| 3 | blocked by CORS policy |
プリフライト失敗、Access-Control-Allow-Origin の欠落 |
コンソール+ネットワークのプリフライト |
| 4 | エンドポイントが 404 / 500 | パスの誤り、リソース削除、サーバー例外 | ネットワーク:URL、ステータス、レスポンス概要 |
| 5 | Hydration failed because the initial UI does not match |
サーバーとクライアントの初回描画が不一致 | コンソール+該当コンポーネント |
| 6 | Unhandled promise rejection |
catch のない非同期失敗。エラーが消える |
コンソール+きっかけの操作 |
| 7 | Refused to load ... violates Content Security Policy |
CSP が新しいドメインやインラインスクリプトを許可していない | コンソール+ページの CSP ヘッダー |
| 8 | Mixed Content: ... loaded over HTTPS, but requested an insecure resource |
HTTPS のページが HTTP のリソースを要求 | コンソール+遮断されたリクエスト |
エラー・バグ・欠陥は同じではない
- エラーはシステムからの信号です。警告のこともあれば、ノイズのこともあります。
- バグは実装と期待の不一致で、通常は再現手順が必要です。
- 欠陥(defect)は、正式な管理に入ったバグを多くのツールがこう呼ぶものです。
種類ごとに必要な証拠
| 種類 | 報告に必ず入れる | あると良い |
|---|---|---|
| 構文/実行時 | メッセージ原文、ページ URL、きっかけの操作 | スクリーンショット、短い録画 |
| 参照 | メッセージ原文、失敗したルート、ログイン中のロール | 関連レスポンスの構造 |
| ネットワーク | リクエスト URL、ステータスコード、操作、時刻 | レスポンスの抜粋(機密項目に注意) |
| 論理 | 手順、期待結果、実際の結果、データ例 | 画面録画 |
| 環境 | ブラウザと OS のバージョン、ビューポート、環境識別子(本番/ステージング/プレビュー) | アカウント権限、ビルド番号 |
聞き取りなしで証拠を集める
手作業の道は DevTools を開き、コンソールとネットワークを撮り、時刻を突き合わせる作業です(ブラウザのコンソールを開く)。現実には 3 つの問題があります。非技術の同僚はやらない、撮り漏らす、そして後から時刻を突き合わせる人が要ります。 安い道は、報告ツールに持たせることです。BugCapturer のレポートにはページ URL(機密パラメータはマスク)、ブラウザと OS、画面とビューポート、タイムスタンプ、コンソールエラーの原文、失敗したリクエスト(4xx/5xx)とステータスコードが自動で付きます。報告者は問題箇所を囲み、見えた現象を 1 文書くだけ。残り 5 列は自動です。 差が出るのは提出率です。コンソールを覚えてもらう前提だと、非技術の同僚の大半が入口で脱落します。ページ上で直接注釈するから 2 回目も出してもらえます。「エラー種別」フィールドは必要か
すでに数百件のレポートがあるなら、error_type フィールドには価値があります。ただし条件は 3 つです。
よくある 3 つの誤り
- 赤い行をすべてバグ扱いする:拡張、解析スクリプト、広告ブロッカーもコンソールに書き込みます。判断基準は「ページの挙動が変わるか」です。
- 警告を無視する:React の key 警告、ハイドレーション警告、非推奨警告はバグではありませんが、その前触れであることが多いです。
- 500 をそのままバックエンドへ回す:ステータスはサーバー失敗を示しますが、報告には URL、パラメータ名、操作が欠けています。この 3 つがないと「もう一度再現してください」で終わります。
よくある質問
構文エラーはバグですか? ソース上の構文エラーは通常ビルドで止まり、本番には出ません。本番でSyntaxError が出るなら公開パイプラインの問題(ビルド未検証、CDN が古いファイルを返す)で、欠陥として扱います。
コンソールの警告は報告に入れるべきですか?
現象に関係するものだけです。真っ白な画面とハイドレーション警告なら入れます。ライブラリの非推奨通知は入れません。本当の手がかりが埋もれます。
「API 500」はフロントとバックのどちらに報告しますか?
修正の担当は運用次第ですが、報告内容は同じです。URL、ステータスコード、操作、時刻、再現性。まずフロントが誤ったパラメータを送ったのか、サーバーが本当に失敗したのかを切り分けます。
なぜ開発者は「再現できません」と言うのですか?
足りないのは手順ではなく環境です。権限、データ量、ブラウザのバージョン、タイムゾーン、feature flag が違います。環境フィールドがあればその往復が消えます。
非技術の同僚に有用な報告をしてもらうには?
DevTools を教えないことです。ブラウザ拡張を入れ、またはサイトに埋め込みのフィードバック入口を置き、コンソールと失敗リクエストをツールに集めさせます。これはインスタントフィードバックシステムが成立する前提でもあります。