n8n-validation-expert

n8n 検証エキスパート

n8n の検証エラーを解釈して修正するためのエキスパートガイドです。

---

検証の基本方針

早めに検証し、頻繁に検証しましょう

検証は通常、反復的に行われます。

• 検証のフィードバックループを想定してください
• 通常、検証 → 修正を2〜3回繰り返します
• エラーについて考える時間の平均は23秒、修正する時間の平均は58秒です

重要なポイント：検証は一度きりではなく、反復的なプロセスです！

---

エラーの重大度

1. エラー（必ず修正）

ワークフローの実行を妨げます — 有効化する前に解決する必要があります

種類：

• missing_required - 必須フィールドが指定されていません
• invalid_value - 値が許可された選択肢と一致しません
• type_mismatch - データ型が間違っています（数値ではなく文字列など）
• invalid_reference - 参照先のノードが存在しません
• invalid_expression - 式の構文エラーです

例：

{
  "type": "missing_required",
  "property": "channel",
  "message": "Channel name is required",
  "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
}

2. 警告（修正を推奨）

実行は妨げません — ワークフローは有効化できますが、問題が発生する可能性があります

種類：

• best_practice - 推奨されますが、必須ではありません — ai-friendly／strict でのみ表示されます
• deprecated - 古い API／機能を使用しています — すべてのプロファイルで表示されます
• security - ハードコードされたシークレット、認証されていない Webhook など — すべてのプロファイルで表示されます
• performance - パフォーマンス上の問題の可能性があります — 助言であり、ai-friendly／strict で表示されます

例（ベストプラクティス — ai-friendly／strict で表示）：

{
  "type": "warning",
  "nodeName": "Slack",
  "message": "Slack API can have rate limits and transient failures"
}

3. 提案（任意）

あると便利です — ワークフローを改善できる提案です

種類：

• optimization - より効率的にできる可能性があります
• alternative - 同じ結果を得るためのより良い方法です

---

検証ループ

テレメトリーから見られるパターン

このパターンは7,841回発生しています：

1. Configure node
   ↓
2. validate_node (23 seconds thinking about errors)
   ↓
3. Read error messages carefully
   ↓
4. Fix errors
   ↓
5. validate_node again (58 seconds fixing)
   ↓
6. Repeat until valid (usually 2-3 iterations)

例

// Iteration 1
let config = {
  resource: "channel",
  operation: "create"
};

const result1 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "name"

// ⏱️  23 seconds thinking...

// Iteration 2
config.name = "general";

const result2 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "text"

// ⏱️  58 seconds fixing...

// Iteration 3
config.text = "Hello!";

const result3 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Valid! ✅

これは正常です！ 繰り返しが何度あっても気にしないでください。

---

検証プロファイル

4つのプロファイルは累積的です（n8n-mcp ≥ 2.63.0）。それぞれ、下位のプロファイルで表示されるすべての項目に加えて、さらに多くの項目を表示します。違いを分けるのはベストプラクティスの助言です。minimal と runtime では表示されず、ai-friendly と strict では表示されます。minimal が一部の設定レベルのチェック（明示的な operation の列挙値検証など）を省略する点を除き、エラーはすべてのプロファイルで同じです。セキュリティと非推奨に関する警告は、すべてのプロファイルで表示されます。

minimal

使用する場面：ワークフローを組み立てながら、構造をすばやくチェックするとき。

表示される項目：実行を停止させる重大なエラー（必須フィールドの欠落、コードが空、接続の破損など）。列挙値のチェックと、すべての助言は省略されます。

最速で、最も制約の少ないプロファイルです。

runtime（推奨のデフォルト）

使用する場面：ワークフローの作成中に継続して検証するとき。日常的な使用向けのプロファイルです。

表示される項目：エラー（必須フィールド、値の型、許可された値、依存関係、参照の破損）に加え、セキュリティと非推奨に関する警告です。ベストプラクティスの助言は表示されません。

バランスの取れたプロファイルです。問題を引き起こすものをすべて検出し、スタイルについては静かです。

ai-friendly

使用する場面：デプロイ前に、ベストプラクティスに関する助言が必要なとき。

表示される項目：runtime のすべての項目に加えて、ベストプラクティスの助言が表示されます。ノードごとの「エラー処理なし」の提案、「Webhook は常にレスポンスを送信すべき」という提案、レート制限に関する注意、古い typeVersion の提案、cachedResultName と長いチェーンに関するヒントなどです。

注：ai-friendly は runtime より厳格であり、緩やかではありません。（以前のドキュメントでは誤検知を減らすと説明されていましたが、それはプロファイルによる制御が壊れていたときだけ正しく、現在は修正されています。）

strict

使用する場面：本番環境で重要なワークフローを強化するとき。

表示される項目：ai-friendly のすべての項目に加えて、未使用プロパティのチェックが表示されます（「プロパティ 'X' は使用されません — 現在の設定では表示されません」）。

最も厳格なリンターです。 誤検知は根本から修正されているため、警告は無視すべきノイズではなく、検討すべき助言です。

よくあるエラーの種類

発生頻度のおおよその順に並べた、5つの主要なエラーの種類です。

• missing_required — 必須フィールドが指定されていません。get_node で必須フィールドを確認し、追加してください。
• invalid_value — 値が許可された選択肢と一致しません（列挙型は大文字と小文字を区別します）。エラーに記載された許可リストまたは get_node を確認してください。
• type_mismatch — データ型が正しくありません（文字列 "100" と数値 100 など）。期待される型に変換してください。
• invalid_expression — 式の構文エラーです（{{}} の欠落、入力ミスなど）。n8n Expression Syntax スキルを参照してください。
• invalid_reference — 参照先のノードが存在しません（名前の変更、削除、または入力ミス）。名前を修正するか、cleanStaleConnections を使用してください。

6つ目の種類である patchNodeField エラー（検索対象が見つからない、あいまいな一致、無効または危険な正規表現）は、n8n_update_partial_workflow 中に patchNodeField オペレーションが失敗したときに発生します。これは意図的に厳格な設計になっており、黙って処理を続けるのではなくエラーになります。

上記すべての種類について、動作する例（問題のある設定 → 修正）と patchNodeField のエラーケースおよびその修正方法が ERROR_CATALOG.md に記載されています。

---

自動サニタイズシステム

一般的なオペレーター構造を自動的に正規化します。n8n_create_workflow、n8n_update_partial_workflow、その他の保存など、ワークフローを更新するたびに適用されます。信頼して使用し、これらを手動で修正しないでください。

保存時に正規化されるもの：

• 二項演算子（equals、notEquals、contains、notContains、greaterThan、lessThan、startsWith、endsWith） — 余分な singleValue プロパティを削除します。
• 単項演算子（isEmpty、isNotEmpty、true、false） — singleValue: true を追加します。
• IF/Switch メタデータ — IF v2.2 以降および Switch v3.2 以降の conditions.options を補完します。

これらの構造は検証時にエラーにならなくなりました（n8n-mcp ≥ 2.63.0）。n8n は演算子名から単項演算子かどうかを判断し、conditions.options のサブフィールドをデフォルト値に設定します。そのため、singleValue とオプションのメタデータの有無にかかわらず、validate_node / validate_workflow は条件を受け入れます。サニタイザーは保存時に標準形式を整えるだけです。（以前のサーバーでは、正規化されていない構造が誤ってエラーになっていました。その場合はアップグレードしてください。）引き続き実際のエラーとなるのは、v2 ノード内の v1 形式の conditions オブジェクト、条件のない空のフィルター、v2 構造内のレガシーな v1 演算子名（例：smaller）です。

サニタイザーで修正できないもの（手動で対処してください）：存在しないノードへの接続不良（cleanStaleConnections を使用）、ブランチ数の不一致（接続またはルールを追加・削除）、および矛盾した破損状態（手動での DB 操作が必要な場合があります）。

修正前後の例と、修正できない項目の詳細は ERROR_CATALOG.md（Auto-Sanitization のセクション）に記載されています。

---

誤検知

バリデーターの全面改修（n8n-mcp ≥ 2.63.0）により、従来の誤検知は解消されました。式内のテンプレートリテラル、オプショナルチェーン、省略された操作のデフォルト値、Webhook → Respond-to-Webhook パターン、IF／Filter のレガシー形式などが誤検知されることはなくなりました。

既知の例外（n8n-mcp 2.85.0、上流で報告済み。アップグレード後に再確認してください）：

• ファンアウト先のいずれかが Respond to Webhook または Send Email ノードである場合、あるいはノード名に error / fail / catch / exception が含まれる場合に発生する ERROR「Incorrect error output configuration… appear to be error handlers but are in main[0]」。提案どおりに Respond to Webhook を main[1] に移動すると、上流ノードが失敗したときにしか Webhook が応答しなくなります。このメッセージがこの文面と完全に一致し、かつ connections を調べて、名前が示されたノードが設計上、成功パスにあることを確認できた場合に限り、誤検知として扱ってください。その場合は配線を維持し、返信で n8n-mcp#1111 を無視する理由を説明してください。また、デフォルトの修正タイプで n8n_autofix_workflow を実行しないでください（error-output-config を除外してください。除外しないと成功パスが再配線される可能性があります）。それ以外の valid: false エラーはすべて修正してください。(n8n-mcp#1111)
• 文字列内の json／items に対する Warning「Possible missing $ prefix」。例：$jmespath($('X').all(), "[?json.country=='PL'].json.name")。ここでは json. プレフィックスが必要なので、この警告は無視してください。(#1115)
• language: "pythonNative" の Code ノードに対する validate_node →「Code cannot be empty」（jsCode）。このエラーは誤りです。代わりにワークフローを検証してください。(#1112)
• すべての項目モードで単一の辞書を返す場合の Python「Return value must be a list of dicts」。n8n では受け入れられ、項目が 1 つ出力されます。(#1113)

見落としやすい問題（ワークフローは有効だが、実行時の結果が誤っている）： 式内の $jmespath 構文／引用符の誤り（#1114）；{{ }} 内のあらゆる JS エラー。実行は成功扱いのまま、値が null になります（n8n-expression-syntax を参照）；レガシーな _input／_json、ドットアクセス、ブロックされたインポートやクラスなどのネイティブ Python の誤り（#1113、n8n-code-python を参照）。検証に通り、実行にも成功したからといって、それだけで正しいとは限りません。出力値を確認してください。

残っているのはベストプラクティスに関する警告です（ai-friendly／strict プロファイルでのみ表示されます）。実際のトレードオフを指摘するものですが、状況によっては許容できる場合があります。すべての警告を修正する必要はありません。多くは状況に依存します。よくある警告と、それぞれを許容できる場合／修正する価値がある場合を以下に示します。

• 「...without error handling」 — 開発／テストや重要度の低い通知では問題ありません。重要なデータを扱う本番環境では修正してください。（ハードエラーではありません。スタイルに関する警告のため、実行はブロックされません。）
• 「No retry logic」 — 冪等な操作、独自の再試行機能がある API、手動トリガーでは問題ありません。不安定な外部サービスや本番環境の自動化では修正してください。
• 「...rate limits and transient failures」 — 内部向け／低トラフィックの API や、サーバー側で制限されている API では問題ありません。公開 API や高トラフィックの API では修正してください。
• 「Unbounded query」 — 少量で既知のデータセット、集計、開発／テストでは問題ありません。大規模テーブルに対する本番クエリでは修正してください。

一方、セキュリティと非推奨に関する警告は、すべてのプロファイルで表示されるため、実際の問題として扱ってください。

ケースごとの詳細なガイダンス、バリデーターが検出しなくなった項目の一覧、プロファイル戦略、「修正すべきか？」の判断基準、許容した警告の記録方法については、FALSE_POSITIVES.md を参照してください。

---

検証結果の構造

完全なレスポンス

{
  "valid": false,
  "errors": [
    {
      "type": "missing_required",
      "property": "channel",
      "message": "Channel name is required",
      "fix": "Provide a channel name (lowercase, no spaces)"
    }
  ],
  "warnings": [
    {
      "type": "best_practice",
      "property": "errorHandling",
      "message": "Slack API can have rate limits",
      "suggestion": "Add onError: 'continueRegularOutput'"
    }
  ],
  "suggestions": [
    {
      "type": "optimization",
      "message": "Consider using batch operations for multiple messages"
    }
  ],
  "summary": {
    "hasErrors": true,
    "errorCount": 1,
    "warningCount": 1,
    "suggestionCount": 1
  }
}

読み方

1. まず valid を確認します — true は設定が有効であることを、false はデプロイ前に修正すべきエラーがあることを示します。
2. まず errors を修正します — 各エラーには property、message、fix が含まれています。これらは解決する必要があります。
3. warnings を確認します — 各警告には message と suggestion があります。対応するかどうかはケースごとに判断します（上記の誤検知を参照してください）。
4. suggestions を検討します — 任意の改善案であり、必須ではありません。

---

ワークフローの検証

validate_workflow（構造）

個々のノードだけでなく、ワークフロー全体を検証します

確認項目：

1. ノード設定 - 各ノードが有効か
2. 接続 - 参照切れがないか
3. 式 - 構文と参照が有効か
4. フロー - ワークフロー構造が論理的か

例：

validate_workflow({
  workflow: {
    nodes: [...],
    connections: {...}
  },
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

よくあるワークフローエラー

1. 接続切れ

{
  "error": "Connection from 'Transform' to 'NonExistent' - target node not found"
}

修正方法：古い接続を削除するか、不足しているノードを作成します

2. 循環（エラーではなく警告）

{
  "warning": "Workflow contains a cycle: Node A → Node B → Node A"
}

循環は重大なエラーではなく警告です（n8n-mcp ≥ 2.63.0）。実行時に制御されるループ（エラー時の再試行、データ駆動型のページネーション、フィードバック接続されたルーター）は最後まで実行され、正当なものです。ループが意図しない場合にのみ修正します。無限に回り続けないよう、循環に実際の終了条件（条件ノード、エラー出力、または上限のあるカウンター）があることを確認してください。

3. 複数の開始ノード

{
  "warning": "Multiple trigger nodes found - only one will execute"
}

修正方法：余分なトリガーを削除するか、別々のワークフローに分割します

4. 未接続のノード

{
  "warning": "Node 'Transform' is not connected to workflow flow"
}

修正方法：ノードを接続するか、使用していない場合は削除します

---

復旧方法

方法 1：最初からやり直す

使用する場合：設定が大きく壊れている

手順：

1. get_node で必須フィールドを確認します
2. 最小限の有効な設定を作成します
3. 機能を段階的に追加します
4. 追加するたびに検証します

方法 2：二分探索

使用する場合：ワークフローの検証は通るものの、実行結果が正しくない

手順：

1. ノードの半分を削除します
2. 検証してテストします
3. 動作する場合：問題は削除したノードにあります
4. 動作しない場合：問題は残りのノードにあります
5. 問題を特定できるまで繰り返します

方法 3：古い接続を整理する

使用する場合：「Node not found」エラーが発生する

手順：

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{
    type: "cleanStaleConnections"
  }]
})

方法 4：自動修正を使う

使用する場合：自動で解決できる検証エラーがある

手順：

// Preview fixes (default - doesn't apply)
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false,
  confidenceThreshold: "medium"  // high, medium, low
})

// Review fixes, then apply
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

---

自動修正機能

n8n_autofix_workflow ツールは、次の種類の問題を修正できます。

1. expression-format - 式の先頭に = がない場合に補います（例：{{ $json.field }} → ={{ $json.field }}）
2. typeversion-correction - サポートされていない typeVersion を持つノードをダウングレードします
3. error-output-config - 競合する onError 設定を削除します
4. node-type-correction - 類似度照合を使って、不明なノードタイプを修正します（信頼度 90% 以上）
5. webhook-missing-path - path 設定がない Webhook ノードに UUID を生成します
6. typeversion-upgrade - 自動移行により、ノードを最新バージョンへスマートにアップグレードします
7. version-migration - 手動の手順が必要な、複雑で互換性を破る変更へのガイダンスを提供します

信頼度レベル：high（90% 以上、自動適用しても安全）、medium（70～89%、確認を推奨）、low（70% 未満、手動での確認が必要）

// Preview all fixes
n8n_autofix_workflow({id: "workflow-id"})

// Only apply high-confidence fixes
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true,
  confidenceThreshold: "high"
})

// Target specific fix types
n8n_autofix_workflow({
  id: "workflow-id",
  fixTypes: ["expression-format", "typeversion-upgrade"],
  applyFixes: true
})

更新後のガイダンス：バージョンをアップグレードする場合は、応答の postUpdateGuidance フィールドで、段階的な移行手順を確認してください。

---

ベストプラクティス

✅ 推奨事項

• 重要な変更を加えるたびに検証します
• エラーメッセージを最後まで読みます
• エラーを一つずつ順番に修正します
• デプロイ前には runtime プロファイルを使用します
• 成功したと決めつける前に、valid フィールドを確認します
• 演算子に関する問題には、自動サニタイズを活用します
• 要件が不明な場合は get_node を使用します
• 許容する誤検知を記録します

❌ 避けるべきこと

• 有効化する前の検証を省略する
• すべてのエラーを一度に修正しようとする
• エラーメッセージを無視する
• 開発中に strict プロファイルを使用する（警告が多すぎます）
• 検証が通ったと思い込む（必ず結果を確認してください）
• 自動サニタイズで解決できる問題を手動で修正する
• 未解決のエラーがある状態でデプロイする
• すべての警告を無視する（重要なものもあります！）

---

検証後のワークフローの実行

validate_workflow は構造、パラメーター、式をチェックしますが、実際に実行することはありません。検証に問題がなくても、実データでは失敗することがあるため、完了とする前に一度実行してください。

Webhook、フォーム、チャットのトリガーがある場合： n8n_test_workflow({workflowId}) — デフォルトの method: "auto" はトリガーを検出し、HTTP 経由で実行します（ワークフローがアクティブである必要があります）。

このようなトリガーがない場合（Manual Trigger、Schedule、サブワークフロー）は、HTTP のエントリーポイントがありません。n8n 自身の MCP サーバーを通じて実行するピンデータの方法を使います（N8N_MCP_ACCESS_TOKEN、n8n 2.34 以降）。

1. n8n_test_workflow({workflowId, method: "prepare"}) — ピン留めデータが必要なノードを一覧表示します。
2. 一覧表示されたノードごとにサンプルアイテムを 1 つ作成します。キーにはノードの名前を使い、各アイテムを {json: {...}} でラップします。

   {"When clicking 'Test workflow'": [{"json": {"orderId": "1234", "email": "[email protected]"}}]}
   

   ここでは、{json} アイテムの配列ではなくフラットなオブジェクトを渡してしまうのがよくある間違いです。
3. n8n_test_workflow({workflowId, method: "pinned", pinData}) — そのデータを使って実行し、結果を待ちます。

ピンデータを使わずに手早く手動実行する場合は、 method: "direct" で手動実行を開始し、実行が始まるとすぐに応答が返ります。結果を確認するには、n8n_executions({action: "get", id: executionId, mode: "error"}) をポーリングしてください。direct 実行では何もピン留めされないため、すべてのノードが実行され、外部への呼び出しも実際に行われます。また、pinned でピン留めされるのはトリガー、認証情報を使うノード、HTTP Request ノードのみです。executionMode: "production" は実行コンテキストを変更するものであり、副作用の有無は変わりません。ユーザーから本番実行を求められていない限り、デフォルトのままにしてください。

method: "auto" がワークフローを n8n の MCP サーバー経由で実行することはありません。 外部トリガーのないワークフローではその旨を報告し、prepare／pinned／direct を案内します。ルーティングされる各メソッドは、名前を指定して依頼した場合にのみ実行されます。

最初にルーティング実行する前に同意を得てください。 n8n は、「Available in MCP」設定がオフのワークフローに対するこれらの呼び出しを拒否し、WORKFLOW_NOT_EXPOSED を返します。exposeToMcp: true を付けて再実行すると、その設定をオンにして一度だけ再試行します。これはワークフロー上で確認できる永続的な設定です（有効化するとワークフローが更新されるため、同時に行われた UI 編集が上書きされる可能性があります）。これを渡す前にユーザーに確認してください。 同意のフローで設定が有効になることはあっても、暗黙的に無効になることはありません。再び無効にするには、n8n_update_partial_workflow({id: workflowId, operations: [{type: "updateSettings", settings: {availableInMCP: false}}]}) を実行するか、n8n UI のトグルを使います。

結果の確認： 実行開始後に失敗した場合は、executionId とともに EXECUTION_FAILED が返されます。n8n_executions({action: "get", id, mode: "error"}) で調べ、エラーを発生させたノードから修正して、再度検証して実行してください。

---

既存のワークフローのレビュー

作成中に検証する（上記のループ）のは、自分が作業中のワークフローにあるスキーマや形状のエラーを見つけるためです。既存のワークフローをレビューする場合（自分のものでも、引き継いだものでも）は別の作業です。ワークフローはすでに validate_workflow を問題なく通過していますが、検証では検出できない問題（気づきにくい接続の不具合、インジェクションされやすいクエリ、アイテムを落とす Switch、Set/Code のアンチパターン、エラーパスの欠落など）を探します。その場合は n8n_get_workflow でワークフローを取得し、REVIEW_CHECKLIST.md に沿って確認してください。これは重大度別（MUST FIX／SHOULD FIX／NICE TO HAVE）の監査リストで、各項目から修正に使う標準スキルを参照できます。併せて n8n_audit_instance を実行すると、インスタンス全体にわたるハードコードされたシークレットや認証されていない Webhook を見つけられます。

---

詳細ガイド

包括的なエラーカタログ、誤検知、ワークフローのレビューについては、以下を参照してください。

• ERROR_CATALOG.md - エラーの種類を例とともに網羅した一覧
• FALSE_POSITIVES.md - 警告を許容できる場合
• REVIEW_CHECKLIST.md - 既存のワークフローをレビューするための重大度別監査リスト

---

概要

要点：

1. 検証は反復的です（平均2～3サイクル、23秒＋58秒）
2. エラーは修正が必要ですが、警告への対応は任意です
3. 自動サニタイズにより、保存時にオペレーター構造が正規化されます。生の構造に対する検証エラーは発生しなくなります
4. デフォルトではランタイムプロファイルを使用し、ベストプラクティスに関する助言が必要な場合は ai-friendly／strict に切り替えてください
5. 以前からあった誤検出は修正済みです（≥ 2.63.0）。残っている警告は助言、またはセキュリティ／非推奨に関する通知であり、バリデーターの誤りではありません
6. エラーメッセージを読んでください。修正方法が記載されています

検証プロセス：

1. 検証 → エラーを読む → 修正 → 再度検証
2. 有効になるまで繰り返します（通常2～3回）
3. 警告を確認し、許容できるかどうかを判断します
4. 自信を持ってデプロイします

関連スキルとツール：

• n8n MCP Tools Expert - 検証ツールを正しく使用する
• n8n Expression Syntax - 式のエラーを修正する
• n8n Node Configuration - 必須フィールドを理解する
• n8n_audit_instance - 予防的なセキュリティ検証（ハードコードされたシークレット、認証されていない Webhook、エラーハンドリングの欠如、データ保持）