n8n-debugging

n8n のデバッグ

問題が発生した場合、原因はほぼ常に次のいずれかです。

1. パラメーターの設定ミス（値や型が間違っている、フィールドが不足している）。
2. 古い前提（覚えているものとはバージョンや動作が異なる）。
3. パスの設定ミスや誤接続（出力インデックスが間違っている、Merge の入力が間違っている、接続が不足している、IF／Switch が間違った分岐に接続されている）。
4. 上流データの消失（中間ノードが $json を独自の出力で置き換えたため、下流の $json.x が、そこにあるはずなのに null として解決される）。修正方法：安定した上流ノードを名前で参照します（$('Earlier Node').item.json.x）。
5. アイテムコンテキストの喪失（Aggregate、Execute Once、または Split Out のフロー後に、n8n が .item の参照先を確定できず、「The expression is referencing... multiple matching items」のようなエラーが発生する）。修正方法：Merge ノードでコンテキストを再確立する、明示的な検索に $input.all().find(...) を使う、またはアイテムの対応関係が安定するように設計し直す（たとえば、ステートレスなサブワークフローに分割する）。
6. 論理エラー（接続もパラメーターも正しいのに、ワークフローが期待どおりに動作しない。コードのロジックバグと同じです）。
7. 実際のバグ（まれですが、存在します）。

体系的に診断してください。まず簡単な確認を行い、それで解決しない場合に限り、詳しく調査します。

絶対に守ること

ユーザーの話を信じてください。「動きません」という言葉は、症状の説明が正確でなくても、期待どおりに動作していないことを意味します。「動くはずです」や「本当に X をしていますか？」といった返答で片付けないでください。まず調査します。何が起きるべきかについてはユーザーの話が、実際に何が起きているかについては実行データとソースが真実です。原因を特定できない場合は、もっともらしい作り話をするよりも、「まだわかりません」と答えるほうが適切です。

優先して確認する項目（原因と簡単な確認方法）

原因と簡単な確認方法を、可能性の高い順に対応させます。

1. パラメーターの設定ミス → get_node_types で再取得し、get_workflow_details と照合して、型、値、フィールドの不足による不一致を探します。問題のノードに対してのみ validate_node_config を実行すると、パラメーターごとのエラーが直接返されます。ネストが深い、または条件付きの構造を持つノードでは、差分を目視で確認するよりも高速です。

2. 古い前提 → n8n のバージョンを尋ね、ユーザーが最後にスキルプラグインを更新した時期を尋ねます。動作がスキルの説明と矛盾する場合は、仕様の変化を疑います。

3. パスの設定ミスや誤接続 → get_workflow_details で connections オブジェクトを確認します。Merge の入力が一致しない場合は、n8n-node-configuration の references/MERGE_NODE.md を参照してください。

4. 上流データの消失 → $json.x の参照をチェーンに沿ってたどり、json を独自の出力で置き換えているノードがないか確認します。よくある原因は、Aggregate、HTTP-binary、Extract from File、"Run for All Items" モードの Code、分岐した Merge です。これらに限りません。出力の形状に上流フィールドが含まれていない場合、どのノードでもこの問題が起きる可能性があります。

5. アイテムコンテキストの喪失 → Aggregate／Execute Once／Split Out の後に .item の参照がないか確認し、$input.all().find(...) または Merge のアンカーに切り替えます。

6. 論理エラー → get_execution でデータをステップごとに追跡し、各ノードの出力を期待される結果と比較します。

7. 実際のバグ → まず n8n のソースを読み、次に GitHub の Issue を確認し、その後に回避策を探します。

外部 API の問題については、上流サービスの API ドキュメントが（n8n のラッパーではなく）正しい情報源です。必要に応じて、API ドキュメントと n8n のソースコードを取得してデバッグしてください。

手順を追った確認

上記の簡単な確認ですぐに原因を特定できない場合は、次の手順を順番に進めてください。

Step 1: 症状を確認する

次の点を尋ねます。

• 何を期待していましたか？
• 実際には何が起きましたか？
• エラーメッセージの文面は何ですか？
• 最後に正常に動作したのはいつですか？それ以降に何が変わりましたか？

曖昧な説明（「壊れています」）でも、具体的な内容（「メールが間違ったアドレスに送信される」や「ワークフローが空の本文で 500 を返す」）を尋ねれば、対処できるようになります。

Step 2: 実行を確認する

get_execution({ executionId: <execution_id>, workflowId: <workflow_id>, includeData: true })

次の点を確認します。

• どのノードで失敗しましたか？
• そのノードにはどのような入力がありましたか？
• エラーメッセージは何ですか？ 注意深く読んでください。通常、原因を示しています。

実行 ID がない場合は、ユーザーに再実行を依頼してください。

ステップ 3：ワークフローを再取得する

get_workflow_details({ workflowId: <workflow_id> })

実際の現在の状態を確認します。ユーザーは別のワークフローを見ているか、古いバージョンを覚えている可能性があります。

次の点を比較します。

• ノードとユーザーの想定。
• 接続と意図：get_workflow_details で取得し、connections オブジェクトを SDK コードと比較します。
• 認証情報と想定（n8n-credentials-and-security に従います）。
• 上流データ除去のリスク： データソースと下流の $json.x コンシューマーの間に、独自の出力で json を置き換えるノードがないか確認します。よくある該当例は HTTP-binary、Extract from File、Aggregate、「Run for All Items」モードの Code、分岐を含む Merge ですが、出力の形状に上流フィールドが含まれていなければ、どのノードでも発生する可能性があります。コンシューマーでは $json ではなく、ソースノードを名前で参照する必要があります（$('Source Node').item.json.x）。そうしないと、フィールドが気づかないうちに null として解決されます。
• アイテムコンテキストのリスク： Aggregate／Execute Once／Split Out の後に、下流の .item 参照がないか確認します。n8n ではアイテムを決定的にペアリングできない場合があります。過去の実行で「The expression is referencing... multiple matching items」を探します。

ステップ 4：ノードタイプを再取得する

get_node_types([{ name: '<failed-node>', resource: '...', operation: '...' }])

実際のパラメーターの形状と設定を比較します。よくある不一致は次のとおりです。

• 必須パラメーターがない。
• 型が異なる（文字列と数値など）。
• n8n の UI の型ドロップダウンでは、object と array は別の型です（Set、IF、Switch、Filter など、UI で型を選択する場所）。object を選択しても配列値は受け付けられず、その逆も同様です。式自体の中では通常の JS なので（配列もオブジェクトです）、この違いが影響するのは UI で型を選択する箇所だけです。={{ ... }} 式が、型指定されたスロットに誤ったコンテナーの形状を返す場合は注意します。
• 親が設定されていない依存パラメーター（例：authentication !== 'none' でないのに credentials が設定されている、または operation === 'executeQuery' でないのに query が設定されている）。適切な判別値を渡して get_node_types で再取得します。

手動で形状と設定の差分を比較するのが面倒な場合（深いパラメーター、AI ツールのサブノード、多数の条件分岐など）は、validate_node_config を直接実行します。失敗ごとに { path, message } を返します。ツールのサブノードでは isToolNode: true を設定します。

ステップ 5：ピン留めデータでテストする

prepare_test_pin_data({ workflowId: '<id>' })
test_workflow({ workflowId: '<id>' })

制御された入力を使うと、「ワークフローが壊れているのか」と「入力がおかしいのか」を切り分けられます。ピン留めデータでは動作し、実際の入力では失敗する場合、問題は実際の入力の処理にあります。

ピン留めデータでも誤った出力が生成される場合は、ロジックエラーの可能性が高いです。各ノードの出力を、想定した内容と照らし合わせて追跡します。テスト実行で get_execution を使うと、各ステップで実際に出力されたデータを確認できます。各ノードが何をしたかを判断する際は、このデータが正となります。

ステップ 6：n8n のソースコードを読む

すべて確認しても、動作がおかしいと思われる場合は、次を確認します。

github.com/n8n-io/n8n

• 組み込みノードは packages/nodes-base/nodes/<NodeName>。
• 実行ロジックは packages/cli/src/...。
• ワークフローのランタイムは packages/core/src/...。

コードの動作が事実です。

references/FETCHING_N8N_SOURCE.md を参照してください。

ステップ 7：どちらかのバージョンのずれを疑う

ステップ 1〜6をすべて確認しても動作が期待どおりでない場合、残る原因として最も可能性が高いのはバージョンのずれです。次の2つは、それぞれ独立してずれていきます。

• **相手の n8n インスタンスのバージョン。**確認してください。（UI：Settings → About、または GET /rest/settings。）古いインスタンスでは、このスキルが想定するパラメーターやツールが存在しない場合があります。非常に新しいインスタンスでは、パラメーターの形式やツール名が変わっている場合があります。最新の n8n リリースへの更新を提案してください。修正のうわさがある場合や、問題が最近発生した場合は、最新のベータ版への更新を提案してください。
• **このスキルプラグインのバージョン。**これらのスキルは、時間の経過とともに n8n との間にずれが生じます。ユーザーがしばらく前にプラグインをインストールしていた場合は、スキルのリポジトリで git pull（またはプラグインマネージャーの更新コマンド）を実行するよう提案してください。README の「Drift」セクションを参照してください。

ずれは、get_node_types におけるパラメーター形式の不一致、存在しない、または新しいパラメーターを持つ MCP ツール、スキルの説明と矛盾するツールの説明、スキルの主張と異なる動作として表面化します。こうした問題を見つけたら、ずれの可能性を明確にユーザーに伝えてください。「お使いの n8n のバージョンと、これらのスキルの間にずれがある可能性があります。n8n のバージョンと、スキルを最後に更新した時期を教えていただけますか？」

両方を更新しても問題が解決しない場合は、ステップ 8 に進んでください。

ステップ 8：報告するか、回避策を講じる

バグが確認された場合：

• https://community.n8n.io に質問を投稿するようユーザーに案内します。
• 再現手順を明確にしてユーザーに提示します。
• n8n の GitHub の Issue を確認します。すでに報告されている可能性があります。
• 作業を妨げる場合は、別のノードや方法で回避し、ワークフローのメモに記載します。
• 修正が進行中の場合は、回避策に `` のマークを付けます。

参照ファイル

ファイル	確認するタイミング
references/PARAMETER_VERIFICATION.md	パラメーターの設定に問題がある可能性があり、体系的に再確認する必要がある場合
references/FETCHING_N8N_SOURCE.md	n8n の動作がドキュメントと矛盾し、実際のコードを読む必要がある場合

アンチパターン

アンチパターン	問題点	対処法
「動くはずです。X を実行しているか確認してもらえますか？」	ユーザーの報告を退け、実際の問題を見逃します	ユーザーの話を信頼し、調査してください。
実行内容を確認せずに再実行する	同じ失敗を繰り返すだけで、新しい情報が得られません	失敗した実行で get_execution を実行し、エラーを確認してください
動作が矛盾しているのに、ドキュメントが正確だと思い込む	誤ったメンタルモデルを受け入れてしまいます	ソースを読んでください。動作が真実です
設定済みのノードが失敗したときに、Code ノードでロジックを再実装する	バグを隠すだけで、根本原因を解決できません	まず原因を特定し、バグが確認された場合にのみ回避策を講じてください
ノードを手当たり次第に削除して二分探索する	時間を無駄にします	get_execution を順に確認し、失敗したノードを直接特定してください
MCP で確認せず、ユーザーに再度スクリーンショットを依頼する	時間がかかり、エラーが発生しやすくなります	get_workflow_details と get_execution を使用してください
バグの原因を理解せずに回避しただけなのに、「修正済み」とする	少し異なる形でバグが再発します	原因を記録してください。回避策を講じる場合は、`` のマークを付けてください
ユーザーの n8n のバージョンや、スキルを最後に更新した時期を尋ねずに「バグ」と断定する	実際の原因はバージョンのずれであることが多く、ユーザーが更新すれば「バグ」が解消します	報告する前に、両方のバージョンを確認してください。ステップ 7 を参照してください。