n8n-debugging-official

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-official の 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_workflow_execution を使ってデータを段階的にたどり、各ノードの出力を期待される結果と比較します。

7. 本物のバグ → n8n のソースを読み、次に GitHub の issue を確認し、その後に回避策を検討します。

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

手順を追った解説

上記の手軽な確認ですぐに原因を特定できない場合は、次の順に進めます。

ステップ 1：症状を確認する

次の点を尋ねます。

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

「壊れています」のような曖昧な報告も、「メールが誤ったアドレスに送信される」や「ワークフローが空の本文とともに 500 を返す」のように具体的にすれば、対処しやすくなります。

ステップ 2: 実行を確認する

get_workflow_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-official に準拠）。
• 上流の欠落リスク: データソースと下流の $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: '...' }])

実際のパラメーターの形状と設定済みの値を比較してください。よくある不一致:

• 必須パラメーターの欠落。
• 型の誤り（string と number など）。
• n8n の UI の型ドロップダウンでは object と array は別物です（Set、IF、Switch、Filter など、UI で型を選ぶよう求められるすべての場所）。object を選んでも array の値は受け付けられず、その逆も同様です。式自体の内部では通常の JS です（array は object です）ので、この区別が問題になるのはそれらの UI の型選択面だけです。型指定されたスロットに対して ={{ ... }} 式が誤ったコンテナ形状を返す場合に注意してください。
• 親を伴わない依存パラメーターのセット（例: authentication !== 'none' を伴わない credentials、operation === 'executeQuery' を伴わない query）。適切な判別子を付けて get_node_types で再取得してください。

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

ステップ 5: 固定データでテストする

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

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

固定データでも誤った出力が生成される場合、それは論理エラーの可能性が高いです。各ノードの出力を期待どおりと照らし合わせて追跡してください。テスト実行に対して get_workflow_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をすべて確認しても動作が期待どおりでない場合、残る原因として最も可能性が高いのはバージョンのずれです。両者のバージョンはそれぞれ独立してずれていきます。

• 相手側の 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 のイシューを確認してください。すでに報告されている可能性があります。
• 作業を妨げている場合は、別のノードや方法で回避し、ワークフローのメモに記載してください。
• 修正作業が進行中の場合は、回避策に `` と記してください

参照ファイル

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

反パターン

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