n8n でエラーが出たときのデバッグ方法 — ログ確認・Error Trigger・Retry 設定まで解説

ワークフローが止まった。どこで何が起きているか分からない。——その状態を解消するための記事です。

この記事では以下の3ステップでエラーに対処できるようになります。

1. Executions ログでどのノードで止まったかを特定する
2. Error Trigger ノードでエラーを自動検知・Slack 通知する
3. Retry 設定で一時的な外部 API エラーを自動リカバリする

著者について: THINK YOU LAB では n8n のエラー通知フローと Python によるエラー監視を本番稼働させています。「エラーが出ても気づかない」状態を解消するための多層エラー検知を実装した経験をもとに書いています。

n8n のエラー確認の基本 — Executions ログを読む

Executions ページへのアクセス

n8n でワークフローが失敗したときの最初の確認場所は Executions（実行履歴） ページです。

1. 左サイドバーで「Executions」をクリック
2. または特定のワークフローを開いて上部の「Executions」タブをクリック

成功した実行は緑、失敗した実行は赤で表示されます。

失敗した実行の確認

赤い実行をクリックすると詳細が開きます。確認できる情報:

• 実行時刻: いつ失敗したか
• エラーメッセージ: 何が原因で失敗したか
• ノードの実行状態: どのノードまで成功して、どこで止まったか

どのノードで止まったかを特定する

実行詳細画面では各ノードが「成功（緑）」「失敗（赤）」「未実行（グレー）」で表示されます。

1. 赤いノードをクリックすると Output パネルが開く
2. Error タブに切り替えるとエラーの詳細が表示される
3. message・description・itemIndex を確認する

itemIndex は「処理中の何番目のアイテムでエラーが起きたか」を示します。大量データ処理時に「どのレコードで失敗したか」を特定できます。

よくあるエラーと対処法

401 Unauthorized（認証情報が間違っている / 期限切れ）

原因: n8n に保存している Credential（API キー・トークン）が間違っているか、有効期限切れ。

対処:

1. 左サイドバーの「Credentials」を開く
2. 該当 Credential を選択して「Test」ボタンをクリック
3. テストに失敗したら API キー・トークンを再発行して更新する

Supabase の Service Role Key をローテーションした際は必ず n8n の Credential も更新してください。

403 Forbidden（権限・スコープ不足）

原因: API キーに必要な権限（スコープ）が付与されていない。

対処:

• Slack: apps の「OAuth & Permissions」でスコープを確認
• GitHub: Personal Access Token の Scope を確認（repo / workflow など）
• Supabase: RLS（Row Level Security）のポリシーを確認

429 Too Many Requests（レート制限）

原因: 外部 API の呼び出し頻度が制限を超えた。

対処:

• Retry on Fail を設定して待機後に自動リトライ（後述）
• ループ処理の前に Wait ノード を挿入してリクエスト間隔を調整

500 Internal Server Error（外部サービス側の問題）

原因: 呼び出し先の外部サービス側の問題。

対処: Retry on Fail で数分後に再試行。一時的な障害は自然に回復することが多いです。

"Cannot read property" — データ参照ミス

原因: 前のノードからのデータ参照パスが間違っている。

対処:

# よくある間違いと正しい参照
誤: {{ $json.message }}
正: {{ $json.body.message }}  ← Webhook v2 のデータは body の下にある

前のノードをクリックして「Output」タブでデータ構造を確認してから式を書く習慣をつけてください。

Webhook が受け取れない

原因: ワークフロー未アクティブ、または テスト URL と本番 URL を混同している。

対処:

1. ワークフローが「Active」になっているか確認
2. テスト URL（/webhook-test/）と本番 URL（/webhook/）を混同していないか確認
3. docker logs n8n でコンテナのログを確認

Webhook ノードの詳細 → n8n Webhook の使い方

Error Trigger ノードでエラーを自動検知する

「エラーが起きても気づかない」という状態が最も危険です。Error Trigger ノードを使って、失敗時に自動で Slack に通知する仕組みを作ります。

Error Trigger の仕組み

1. ワークフロー A がエラーで失敗する
2. ワークフロー A に「Error Workflow」が設定されている
3. Error Workflow の Error Trigger ノードが起動する
4. Slack にエラー通知が送られる

Error Trigger ワークフローの作り方

1. 新しいワークフローを作成し「Error Trigger」ノードを追加
2. 次のノードに「Slack ノード」を追加して通知設定
3. ワークフローを「Active」にする
4. 監視したいワークフローの設定画面 → 「Error Workflow」に上記ワークフローを指定

エラー情報の取得

Error Trigger が受け取るデータ構造:

{
  "error": { "message": "エラーメッセージ", "name": "エラーの種類" },
  "execution": { "id": "実行ID", "url": "実行詳細のURL" },
  "workflow": { "id": "ワークフローID", "name": "ワークフロー名" }
}

Slack 通知のメッセージ例:

*[n8n エラー]* {{ $json.workflow.name }}
エラー: {{ $json.error.message }}
実行ログ: {{ $json.execution.url }}

$json.execution.url を含めると Slack 通知から直接ログへ飛べます。

THINK YOU LAB での多層エラー検知

THINK YOU LAB では2段階のエラー検知を構築しています。

第1層: アプリケーション側の監視

Python スクリプトが実行中のエラーを検知して n8n の Webhook に POST します。

エラー発生（Python スクリプト）
  ↓ POST /webhook/notify
  ↓ {"level": "error", "source": "スクリプト名", "message": "内容"}
n8n WF_notify
  ↓ IF ノード: level で分岐
  ↓ Slack #ops-alert に通知

第2層: n8n 自体のエラー監視

n8n のワークフロー自体が失敗した場合は Error Trigger で捕捉します。

エラーレベルで通知を分ける設計

| level | 通知方法 | 用途 | |---|---|---| | error | 赤アイコン + <!here> メンション | 即対応が必要 | | warn | 黄色アイコン + 通常テキスト | 注意は必要だが緊急でない | | info | 青アイコン + スレッド返信 | 情報ログ（通知量を抑える） |

この設計で Slack の通知疲れを防ぎながら重要なエラーを見逃さない運用を実現しています。

Retry 設定で一時的なエラーを自動リカバリする

Retry on Fail の設定

HTTP Request ノードなどで Retry on Fail を設定できます。

1. ノードをクリックして「Settings」タブを開く
2. 「Retry on Fail」をオンにする
3. Max tries: 最大リトライ回数（例: 3）
4. Wait Between Tries: リトライ間隔（秒。例: 30）

429 エラー（レート制限）には60秒以上の待機時間が有効です。

Continue On Fail と Retry on Fail の違い

| 設定 | 動作 | 用途 | |---|---|---| | Retry on Fail | 指定回数リトライ。全試行失敗でフロー全体を失敗にする | 一時的なエラーの自動リカバリ | | Continue On Fail | エラーでも次のノードに進む。エラー情報を $json.error で後続に渡す | 部分的な失敗を許容したい場合 |

予防的エラーハンドリングの設計パターン

IF ノードで事前にデータを検証する

外部 API を呼ぶ前に必要なデータが揃っているか確認します。

Webhook → IF ノード（body.message が空でないか）
           ├─ True: 処理を続行
           └─ False: デフォルト値をセット → 処理を続行

Set ノードでデフォルト値を設定する

// body.message が空の場合は "(no message)" を設定
{{ $json.body.message || "(no message)" }}

まとめ

エラー対処の3ステップ:

1. Executions ログで失敗ノードを特定 → Error タブでメッセージを確認
2. Error Trigger ワークフローを作成して監視対象 WF に設定
3. Retry on Fail（Max tries: 3 / Wait: 30s）を全 HTTP Request ノードに設定

次のステップ:

• n8n をローカル Docker 環境で起動する手順
• n8n Webhook の使い方
• n8n と Claude AI を組み合わせた自動化ガイド

「n8n でエラーが出るたびに時間を取られる」なら、エラーパターン対処チートシートが役に立ちます。よく遭遇するエラー15パターンと対処法を LINE で無料配布中です。

→ n8n エラー対処チートシート（15パターン）を受け取る（LINE登録・無料）