エラーメッセージの読み方

目次

• 概要
• エラーを分解する
• stack trace
• 原因の連鎖を読む
• exit code
• errnoとOSエラー
• HTTP error
• networkとTLSのエラー
• compiler error
• language別の読み方
• package managerとbuildのエラー
• containerとKubernetesのエラー
• cloudと権限エラー
• 原因調査の手順
• 質問・報告の書き方
• エラー分類マップ
• 最小再現を作る
• エラーをよくする書き方
• エラーの構造化と収集
• 言語別エラーの特徴
• エラーハンドリングのアンチパターン
• エラーハンドリングのベストプラクティス
• エラー調査の実践的フロー
• デバッグツール活用
• エラーとモニタリングの統合
• まとめ
• 参考文献

概要

エラーメッセージは、失敗の原因を探すための地図です。怖いものではなく、システムが「どこで、何が、なぜ失敗した可能性があるか」を教えてくれる情報です。

エラーを分解する

エラーには、いくつかの情報が含まれます。

まず見る順番は、だいたい次です。

長いエラーでは「最初」と「最後」の両方を見ます。最初のエラーは根本原因に近いことが多く、最後のエラーは実際に処理が止まった場所を示すことが多いです。

Caused by: ENOENT: no such file or directory, open './config.json'
...
Error: failed to start server

この場合、最後の failed to start server だけを見ると曖昧です。config.json を開けなかったことが、より具体的な原因です。

stack trace

stack traceは、関数呼び出しの履歴です。

TypeError: user.name is undefined
    at renderUser (src/user.ts:12)
    at renderPage (src/page.ts:45)
    at main (src/main.ts:3)

読む順序です。

1. エラー種別を見る
2. メッセージを見る
3. 自分のコードの最初の行を探す
4. その関数に渡された値を確認する
5. 直前の変更を確認する

ライブラリ内部の行が多くても、必ずしもそこが原因とは限りません。自分のコードから不正な値を渡していることも多いです。

stack traceは上から読むか下から読むかで迷います。多くの場合、上の方に「実際に例外が投げられた場所」があり、下の方に「そこへ至った入口」があります。

TypeError: Cannot read properties of undefined (reading 'name')
    at renderUser (src/user.ts:12:21)
    at renderPage (src/page.ts:45:10)
    at handleRequest (src/server.ts:88:5)

この例では、renderUser が落ちた場所、handleRequest が入口です。修正のためには renderUser の12行目を見るだけでなく、renderPage がどんな user を渡したかも見ます。

stack traceを読むときのコツです。

原因の連鎖を読む

よいエラーは、低レベルの原因に高レベルの文脈を重ねています。

Error: failed to load application config
Caused by: failed to read ./config/production.json
Caused by: No such file or directory (os error 2)

この形では、下に行くほど低レベル、上に行くほどアプリケーション上の意味に近くなります。

原因連鎖を見るときは、「最も低レベルの原因」と「ユーザー影響に近い失敗」の両方をメモします。

Rustの anyhow やGoのwrapped errorのように、低レベルエラーへ文脈を足していく文化があります。読む側は「最後に表示された1行」だけでなく、Caused by、source、wrapped、because を探します。

exit code

CLIでは、終了状態がexit codeで返ります。

npm run build
echo "$?"

CIでは、exit codeが0以外だとjobが失敗します。

shellでは、失敗しても後続コマンドが動くことがあります。

false
echo "still running"

CIやscriptでは、必要に応じて set -euo pipefail のような設定を使います。ただし、これも万能ではありません。pipeの途中で失敗したコマンド、条件分岐内のコマンド、意図的に失敗を許すコマンドを区別します。

set -euo pipefail
curl -fsS https://example.com/health

exit codeを読むときは、次を確認します。

errnoとOSエラー

OSやruntime由来のエラーでは、ENOENT、EACCES、ECONNREFUSED のようなerrno名が出ます。数値は環境差があるため、基本的には名前で読みます。

ENOENT は「そのファイルがない」とは限りません。pathの途中のディレクトリがない、cwdが想定と違う、container内にcopyされていない、symlinkが切れている、という場合もあります。

pwd
ls -la
stat ./config.json

EACCES と EPERM は似ています。EACCES はファイル権限や実行権限の不足、EPERM はより広く「操作自体が許可されていない」場面で出ます。container、macOS sandbox、Linux capability、cloud IAMが絡むと EPERM 的な問題に見えることがあります。

HTTP error

HTTPではstatus codeが大きな手がかりです。

403 と 404 は似て見えますが、原因が違います。権限問題なのか、URLやroutingの問題なのかを分けます。

HTTP errorは、status codeだけでなく、method、URL、response body、response headerを一緒に見ます。

curl -i https://example.com/api/users
curl -v https://example.com/api/users

同じ 403 でも、applicationの権限不足、cloud storageのbucket policy、WAF block、CORS preflightの失敗など、層が違うことがあります。

networkとTLSのエラー

network errorは、アプリケーションのエラーに見えても、DNS、TCP、TLS、proxy、serverのどこでも起きます。

切り分けは、層を下から見ます。

dig example.com
curl -v https://example.com/
openssl s_client -connect example.com:443 -servername example.com

curl -v は、DNS、TCP、TLS、HTTPのどこまで進んだかを見やすくしてくれます。本文よりも、接続ログとheaderが重要なこともあります。

compiler error

compiler errorは、行番号と型の情報をくれます。

error TS2322: Type 'string' is not assignable to type 'number'.

型エラーでは、次を見ます。

• 期待されている型
• 実際に渡した型
• 型が決まった場所
• genericやunionの広がり

最初のエラーが原因で、後続のエラーが連鎖していることがあります。まず最初のエラーから直します。

compiler errorは、runtime errorより親切なことが多いです。型、期待値、実際値、候補、修正案が含まれます。

src/app.ts:12:7 - error TS2322: Type 'string' is not assignable to type 'number'.

読む要素です。

型エラーでは「エラーが出た場所」と「型が決まった場所」が違うことがあります。呼び出し側、型定義、genericの推論、設定ファイルを順番に見ます。

language別の読み方

言語ごとに、エラーの出方には癖があります。

Python tracebackの例です。

Traceback (most recent call last):
  File "app.py", line 10, in <module>
    main()
  File "app.py", line 6, in main
    load_config("config.json")
FileNotFoundError: [Errno 2] No such file or directory: 'config.json'

最後の FileNotFoundError が直接原因です。ただし、load_config を呼んだ文脈も見る必要があります。

Rustでは、panicとrecoverable errorを分けて考えます。

thread 'main' panicked at src/main.rs:10:5:
index out of bounds

panicはバグ寄り、Result で返るerrorは入力や環境の失敗として扱えることが多いです。必要なら RUST_BACKTRACE=1 で追加情報を出します。

package managerとbuildのエラー

build errorは、コードそのものではなく、dependency、lockfile、cache、Node/Python/Rust/Goのversion、OS packageの不足で起きることがあります。

build logは長くなりがちです。最初に出た error、ERR!、Caused by、failed to を探します。

rg -n "error|ERR!|failed|Caused by" build.log

同じlogに warning が大量にあっても、失敗を決めたのは最後のexit codeと、その直前の明確なerrorであることが多いです。

containerとKubernetesのエラー

containerでは、アプリケーションエラーに見えても、image、command、env、volume、network、権限が原因のことがあります。

Kubernetesでは logs と describe をセットで見ます。

kubectl logs pod/api-xxxxx
kubectl logs pod/api-xxxxx --previous
kubectl describe pod/api-xxxxx

logs はアプリケーションの出力、describe はscheduler、image pull、probe、OOM、eventを見る入口です。

cloudと権限エラー

cloudのエラーは、resource、principal、action、conditionに分解します。

AccessDenied: User is not authorized to perform: s3:PutObject on resource ...

AWS S3のようなサービスでは、HTTP statusに加えてservice固有のerror codeが返ります。AccessDenied、NoSuchBucket、NoSuchKey、InvalidAccessKeyId のようなcodeは、HTTP statusより具体的です。

権限エラーでは、credentialが想定通りかを先に確認します。

aws sts get-caller-identity
aws configure list

「権限がない」の前に、「そもそも違うアカウント/roleで実行している」こともよくあります。

原因調査の手順

調査では、同時に多くを変えないことが重要です。1つ変えて、結果を見る。これを繰り返します。

調査ログを残すと、迷子になりにくくなります。

「直したつもりで別のものを壊した」を避けるため、再現コマンドを固定してから変更します。

npm run build

同じコマンドを繰り返し、出力がどう変わったかを見るだけで、かなり調査が安定します。

質問・報告の書き方

質問するときは、相手が再現できる情報を渡します。

• 何をしようとしたか
• 期待した結果
• 実際の結果
• エラーメッセージ全文
• 実行したコマンド
• 環境
• 直前に変えたこと
• 試したこと

悪い例です。

動きません。

良い例です。

npm run buildでdistを生成したいです。
期待: build成功
実際: TypeErrorが発生
環境: Node.js 22, macOS
直前の変更: build/build.jsのリンク生成を変更

さらに良い報告では、再現手順と全文ログを分けます。

目的:
dist/ を生成したい

再現手順:
1. npm ci
2. npm run build

期待:
buildが成功し、dist/index.htmlが生成される

実際:
build/build.js:120でTypeError

エラー全文:
TypeError: Cannot read properties of undefined (reading 'href')
    at buildNavigation (build/build.js:120:18)

環境:
Node.js 24.4.1
macOS

試したこと:
- node_modulesを削除してnpm ci
- build/build.jsの直前変更を確認

質問や報告の目的は、詳しく見せることではなく、相手が同じ状態を再現できるようにすることです。ログ全文は長くてもよいですが、本文では重要な行を先に抜き出します。

エラー分類マップ

エラーは、まず種類で分けると調査しやすくなります。

分類できるだけで、見るべき資料がかなり絞れます。

もう少し実務寄りに分けると、次のようになります。

この分類に沿って「同じコードで環境を変える」「同じ環境で入力を変える」のように1軸ずつ動かすと、原因に近づきやすくなります。

最小再現を作る

原因が分からないときは、最小再現を作ります。最小再現とは、問題を起こすために必要な最小のコード、入力、手順です。

作り方です。

1. エラーメッセージ全文を保存する
2. 入力を小さくする
3. 関係ない依存を外す
4. 1ファイルで再現できるか試す
5. 成功するケースと失敗するケースを並べる

最小再現は、質問のためだけでなく、自分が原因を理解するためにも強力です。削っている途中で原因が見つかることも多いです。

最小再現では、次を削ります。

失敗する例と成功する例を並べると、差分が原因候補になります。

// 成功
parseUser({ name: "Alice" })

// 失敗
parseUser({})

この2つの差は name の有無です。巨大なアプリ全体では見えなかった原因が、小さい入力だと見えます。

最小再現を作るときの落とし穴です。

エラーをよくする書き方

エラーは読むだけでなく、書く側でも改善できます。よいエラーは、原因、対象、文脈、次の行動を含みます。

悪い例です。

failed

少し良い例です。

failed to read config

さらに良い例です。

failed to read config file "./config/production.json": no such file or directory

エラーを書くときの要素です。

エラーに文脈を追加する例です。

try {
  const raw = await fs.readFile(configPath, "utf8");
  return JSON.parse(raw);
} catch (error) {
  throw new Error(`failed to load config from ${configPath}`, { cause: error });
}

ユーザー向けメッセージと開発者向けメッセージは分けます。

security的には、内部情報を出しすぎないことも大切です。

Web APIでは、内部ログには詳細を残し、clientには安定したerror codeとrequest idを返す設計が扱いやすいです。

{
  "error": {
    "code": "CONFIG_NOT_FOUND",
    "message": "configuration is missing",
    "request_id": "req-123"
  }
}

内部ログには、より詳しい原因を残します。

{
  "level": "ERROR",
  "event": "config_load_failed",
  "request_id": "req-123",
  "path": "./config/production.json",
  "error.type": "ENOENT",
  "message": "failed to load config file"
}

エラーの構造化と収集

本番環境では、ばらばらなエラーログでは調査が困難です。エラーを構造化して収集する仕組みが重要です。

エラートレーシング (OpenTelemetry)

OpenTelemetry標準を使うと、trace ID → span ID → event として
分散システムでエラーを追跡できます

request-id: req-abc123
  ├─ span: receive_request (duration: 1ms)
  ├─ span: database_query (duration: 50ms) ← エラー発生
  │   └─ event: connection_timeout
  │       └─ error.type: ETIMEDOUT
  │       └─ error.message: "failed to connect to postgres:5432"
  └─ span: error_response (duration: 2ms)

Jaeger、Datadog、New Relicなどが実装。

エラー分類と監視

エラーの層別:
1. User error (400系) → ドキュメント改善
2. Server error (500系) → 高優先度アラート
3. Transient (timeout等) → リトライ設定確認
4. Permanent (permission等) → 設定・権限確認

ログ検索パターン

実務でよく必要になる検索:

# 特定のuser_idが失敗している場合
user_id: "user-123" AND level: ERROR

# 特定のリソースで詳細ログを取る
resource_id: "resource-456" AND detailed_log: true

# 指定時間帯でのエラートレンド
@timestamp: [2024-01-15T10:00 TO 2024-01-15T11:00] 
AND error.type: ECONNREFUSED

# 特定のスタックトレースパターン
stack_trace: "*ConnectionPool*" AND "*timeout*"

Elasticsearch、Splunk、Cloud Loggingなどのクエリ言語を習得すると、トラブルシューティング速度が大幅向上。

言語別エラーの特徴

Rustのエラー処理

Rustは Result<T, E> 型で明示的なエラー処理を強制:

fn parse_config(path: &str) -> Result<Config, ConfigError> {
    let content = std::fs::read_to_string(path)
        .map_err(|e| ConfigError::FileNotFound(path.to_string(), e))?;
    
    let config = serde_json::from_str(&content)
        .map_err(|e| ConfigError::ParseError(e.to_string()))?;
    
    Ok(config)
}

// 呼び出し側
match parse_config("config.json") {
    Ok(cfg) => { /* process */ },
    Err(ConfigError::FileNotFound(path, _)) => eprintln!("Missing: {}", path),
    Err(ConfigError::ParseError(msg)) => eprintln!("Invalid JSON: {}", msg),
}

Rustのコンパイラは Result を無視できず、エラーハンドリングを忘れない設計。

Pythonの例外処理

try:
    with open("config.json") as f:
        config = json.load(f)
except FileNotFoundError as e:
    logging.error("Config not found", extra={"path": e.filename})
    raise SystemExit(1)
except json.JSONDecodeError as e:
    logging.error("Invalid JSON", extra={
        "line": e.lineno,
        "column": e.colno,
        "msg": e.msg
    })
    raise

try-except での細分化と structured logging が基本。

GoのError型

if err != nil {
    return fmt.Errorf("failed to load config from %s: %w", path, err)
}

// エラーラッピングで context を保持
// %w で原因も含める（Go 1.13+）

Goは明示的なエラーチェックを要求し、panicは避ける文化。

エラーハンドリングのアンチパターン

避けるべきパターン:

エラーハンドリングのベストプラクティス

3層のエラーハンドリング

Layer 1: エラーをキャッチして記録
         logger.exception(...)  # スタックトレース付きログ

Layer 2: ユーザーに伝わる形に変換
         return {"error": "Order could not be processed"}
         HTTP 400 Bad Request

Layer 3: システムは続行 または 停止判定
         if critical: sys.exit(1)
         else: continue

Python での実装

import logging
import traceback
from functools import wraps

logger = logging.getLogger(__name__)

class ApplicationError(Exception):
    """アプリケーション固有エラー"""
    def __init__(self, message, code=None, http_status=500):
        self.message = message
        self.code = code or self.__class__.__name__
        self.http_status = http_status
        super().__init__(self.message)

class ValidationError(ApplicationError):
    def __init__(self, message):
        super().__init__(message, code="VALIDATION_ERROR", http_status=400)

class DatabaseError(ApplicationError):
    def __init__(self, message):
        super().__init__(message, code="DB_ERROR", http_status=500)

def handle_errors(func):
    """デコレータ: 全エラーをキャッチしてログ"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        try:
            return func(*args, **kwargs)
        except ApplicationError as e:
            # アプリエラー: 既知のエラー
            logger.warning(
                f"Application error in {func.__name__}",
                extra={
                    "error_code": e.code,
                    "http_status": e.http_status,
                    "message": e.message
                }
            )
            raise
        except Exception as e:
            # 予期しないエラー
            logger.error(
                f"Unexpected error in {func.__name__}",
                extra={
                    "error_type": type(e).__name__,
                    "traceback": traceback.format_exc()
                },
                exc_info=True
            )
            raise ApplicationError("Internal server error", http_status=500)
    
    return wrapper

@handle_errors
def process_order(order_id, items):
    """エラーハンドリング付き注文処理"""
    # バリデーション
    if not items:
        raise ValidationError("Items cannot be empty")
    
    try:
        # DB操作
        db.save_order(order_id, items)
    except ConnectionError as e:
        raise DatabaseError(f"Could not save order: {str(e)}")
    
    return {"order_id": order_id, "status": "created"}

Rust での結果型（Result）

use std::io;

// Result型: Ok(T) または Err(E)
fn read_config(path: &str) -> Result<Config, io::Error> {
    let content = std::fs::read_to_string(path)?  // ? で自動伝播
    let config: Config = toml::from_str(&content)
        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?
    Ok(config)
}

// 呼び出し側
match read_config("app.toml") {
    Ok(config) => println!("Config loaded: {:?}", config),
    Err(e) => eprintln!("Failed to load config: {}", e),
}

// または ? で伝播
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = read_config("app.toml")?  // エラーならここで return
    println!("{:?}", config);
    Ok(())
}

エラー調査の実践的フロー

5ステップ調査方法

Step 1: エラーメッセージ全体をコピー＆読む
        Type: KeyError
        Message: 'customer_id'
        Occurred at: order.py:42

Step 2: Stack traceを遡る（下から上へ）
        最下部 = 実際のエラー発生箇所
        上層 = そこへいたるコールパス

Step 3: エラー発生時のコンテキストを確認
        入力値, 状態変数, リソースの状態

Step 4: 同じエラーを最小コードで再現
        必要な入力だけで再現可能なコードを書く

Step 5: 根本原因を特定して修正
        修正後、Step 4のテストで検証

よくあるエラーパターン集

デバッグツール活用

Node.js: デバッガー

# Chrome DevTools で デバッグ
node --inspect app.js

# または Node Debugger
node inspect app.js
> c        # 続行
> n        # 次の行へ
> s        # ステップイン
> out      # ステップアウト
> watch(expr)  # 式を監視

Python: pdb (Python Debugger)

import pdb

def problematic_function(x):
    pdb.set_trace()  # ここで停止
    result = x / 0
    return result

# コマンド
# (Pdb) p x          # 変数表示
# (Pdb) l            # ソース行表示
# (Pdb) n            # 次の行へ
# (Pdb) s            # ステップイン
# (Pdb) c            # 続行
# (Pdb) w            # スタックトレース

Go: delve デバッガー

# インストール
go install github.com/go-delve/delve/cmd/dlv@latest

# デバッグ実行
dlv debug main.go

# コマンド
(dlv) break main.main    # ブレークポイント設定
(dlv) continue           # 続行
(dlv) print x            # 変数表示
(dlv) next               # 次の行へ

エラーとモニタリングの統合

Sentry によるエラー追跡

import sentry_sdk
from sentry_sdk.integrations.flask import FlaskIntegration

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    integrations=[FlaskIntegration()],
    traces_sample_rate=1.0,
    release="1.0.0",
    environment="production"
)

@app.route('/order', methods=['POST'])
def create_order():
    try:
        # ビジネスロジック
        return {"status": "created"}
    except Exception as e:
        # Sentryに自動レポート
        sentry_sdk.capture_exception(e)
        # ユーザーには汎用エラーを返す
        return {"error": "Order creation failed"}, 500

出力例（Sentry Dashboard）:

Error: KeyError 'customer_id'
  Release: 1.0.0
  Environment: production
  Affected Users: 47
  First Seen: 2 hours ago
  Last Seen: 5 minutes ago
  Events: 156

まとめ

エラーメッセージは、原因を探すための情報です。種類、場所、理由、文脈に分け、最初のエラーと最後のエラーを見比べると、落ち着いて調査できます。stack trace、exit code、errno、HTTP status、cloud固有のerror codeをそれぞれの層で読み、最小再現で原因を小さくすると、調査はかなり速くなります。

参考文献

公式・標準

• MDN Web Docs: HTTP response status codes
• MDN Web Docs: JavaScript error reference
• Python Documentation: Errors and Exceptions
• Go errors package
• The Rust Programming Language: Error Handling

解説・補助

• Node.js Errors
• Linux man-pages: errno(3)