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 の旧形式などは、誤検知を引き起こさなくなりました。「無視すべき既知の誤検知」のリストはありません。

残っているのはベストプラクティスに関するアドバイザリです（ai-friendly／strict の場合のみ表示）。実際にトレードオフがあることを示しますが、状況によっては許容できるものです。すべてのアドバイザリに対応が必要なわけではなく、多くは状況に応じて判断します。よくある例と、それぞれを許容できる場合／修正すべき場合は次のとおりです。

• 「...エラーハンドリングなし」 — 開発／テストや重要度の低い通知なら問題ありません。重要なデータを扱う本番環境では修正してください。（ハードエラーになることはありません。スタイルに関する警告が実行を妨げることはありません。）
• 「リトライロジックなし」 — 冪等な操作、独自にリトライする API、手動トリガーなら問題ありません。不安定な外部サービスや本番環境の自動化では修正してください。
• 「...レート制限と一時的な障害」 — 内部利用／低トラフィックの API や、サーバー側で制限されている API なら問題ありません。公開 API や高トラフィックの API では修正してください。
• 「上限のないクエリ」 — 小規模で既知のデータセット、集計、開発／テストなら問題ありません。大規模なテーブルに対する本番環境のクエリでは修正してください。

一方、セキュリティと非推奨に関する警告は、すべてのプロファイルで表示されるため、実際の問題として扱う必要があります。

ケース別の詳細なガイダンス、バリデーターが検出しなくなった項目のリスト、プロファイルの戦略、「修正すべきか？」を判断するためのフレームワーク、許容したアドバイザリを文書化する方法については、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 - パス設定がない 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、エラーハンドリングの欠如、データ保持）