n8n Validation Expert

n8n検証エラーの解釈と修正に関するエキスパートガイド。

---

Validation Philosophy

早期に検証し、頻繁に検証する

検証は通常、反復的なプロセスです：

• 検証フィードバックループを予期してください
• 通常、2～3回の検証 → 修正サイクル
• 平均：エラー考察に23秒、修正に58秒

重要な洞察：検証は1回限りのプロセスではなく、反復的なプロセスです！

---

Error Severity Levels

1. Errors（必ず修正）

ワークフロー実行をブロック - アクティベーション前に解決が必須

種類：

• 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. Warnings（修正推奨）

実行をブロックしない - ワークフローはアクティベート可能ですが、問題がある可能性

種類：

• best_practice - 推奨されるが必須ではない
• deprecated - 古いAPI/機能を使用している
• performance - 潜在的なパフォーマンス問題

例：

{
  "type": "best_practice",
  "property": "errorHandling",
  "message": "Slack API can have rate limits",
  "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
}

3. Suggestions（オプション）

あると良い - ワークフローを強化する可能性のある改善

種類：

• optimization - より効率的になる可能性
• alternative - 同じ結果を達成するより良い方法

---

The Validation Loop

テレメトリーから得たパターン

7,841件の発生：

1. ノードを設定
   ↓
2. validate_node（エラーについて23秒考察）
   ↓
3. エラーメッセージを注意深く読む
   ↓
4. エラーを修正
   ↓
5. validate_nodeを再実行（修正に58秒）
   ↓
6. 有効になるまで繰り返し（通常2～3回）

例

// 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! ✅

これは正常です！ 複数のイテレーションで落胆しないでください。

---

Validation Profiles

あなたのステージに合わせて適切なプロファイルを選択してください：

minimal

使用時期：編集中のクイックチェック

検証内容：

• 必須フィールドのみ
• 基本的な構造

長所：最速、最も寛容 短所：問題を見落とす可能性

runtime（推奨）

使用時期：デプロイ前検証

検証内容：

• 必須フィールド
• 値の型
• 許可された値
• 基本的な依存関係

長所：バランスが良く、実際のエラーをキャッチ 短所：いくつかのエッジケースを見落とす可能性

ほとんどのユースケースに推奨されるプロファイル

ai-friendly

使用時期：AI生成の設定

検証内容：

• runtimeと同じ
• 誤検知を削減
• 軽微な問題に対してより寛容

長所：AIワークフローのノイズが少ない 短所：いくつかの疑わしい設定を許可する可能性

strict

使用時期：本番デプロイ、クリティカルなワークフロー

検証内容：

• すべて
• ベストプラクティス
• パフォーマンスの懸念
• セキュリティの問題

長所：最大限の安全性 短所：多くの警告、いくつかの誤検知

---

Common Error Types

1. missing_required

意味：必須フィールドが提供されていない

修正方法：

1. get_nodeを使用して必須フィールドを確認
2. 不足しているフィールドを設定に追加
3. 適切な値を提供

例：

// Error
{
  "type": "missing_required",
  "property": "channel",
  "message": "Channel name is required"
}

// Fix
config.channel = "#general";

2. invalid_value

意味：値が許可されたオプションと一致していない

修正方法：

1. エラーメッセージで許可された値を確認
2. get_nodeを使用してオプションを確認
3. 有効な値に更新

例：

// Error
{
  "type": "invalid_value",
  "property": "operation",
  "message": "Operation must be one of: post, update, delete",
  "current": "send"
}

// Fix
config.operation = "post";  // 有効な操作を使用

3. type_mismatch

意味：フィールドのデータ型が間違っている

修正方法：

1. エラーメッセージで期待される型を確認
2. 値を正しい型に変換

例：

// Error
{
  "type": "type_mismatch",
  "property": "limit",
  "message": "Expected number, got string",
  "current": "100"
}

// Fix
config.limit = 100;  // 文字列ではなく数値

4. invalid_expression

意味：式の構文エラー

修正方法：

1. n8n Expression Syntaxスキルを使用
2. 不足している{{}}またはタイプミスがないか確認
3. ノード/フィールドの参照を確認

例：

// Error
{
  "type": "invalid_expression",
  "property": "text",
  "message": "Invalid expression: $json.name",
  "current": "$json.name"
}

// Fix
config.text = "={{$json.name}}";  // {{}}を追加

5. invalid_reference

意味：参照されたノードが存在しない

修正方法：

1. ノード名のスペルを確認
2. ワークフロー内でノードが存在することを確認
3. 参照を正しい名前に更新

例：

// Error
{
  "type": "invalid_reference",
  "property": "expression",
  "message": "Node 'HTTP Requets' does not exist",
  "current": "={{$node['HTTP Requets'].json.data}}"
}

// Fix - タイプミスを修正
config.expression = "={{$node['HTTP Request'].json.data}}";

6. patchNodeField エラー

意味：n8n_update_partial_workflow中にpatchNodeField操作が失敗した

patchNodeField操作は設計上厳密です - 問題があると静かに続行する代わりにエラーが発生します。これは早期に誤りをキャッチしますが、これらの特定のエラーケースを処理する必要があることを意味します。

エラー：文字列が見つかりません パッチのfind値がターゲットフィールドに存在しません。これは通常、コンテンツがすでに変更されたか、find文字列にタイプミスがあることを意味します。

patchNodeField: find string not found in field "parameters.jsCode"

修正方法：正確な文字列を確認してください。n8n_get_workflowを使用して現在のフィールド値を検査してください。空白と改行が重要です - 不確実な場合は、柔軟な空白マッチングのためにregex: trueで\s+を使用してください。

エラー：曖昧な一致（複数の出現） find文字列がフィールド内に複数回表示されます。replaceAll: trueがない場合、これは曖昧と見なされ拒否されます。

patchNodeField: find string matches 3 times in field "parameters.jsCode" — set replaceAll: true to replace all, or use a more specific find string

修正方法：すべての出現を置換したい場合はreplaceAll: trueを設定するか、意図した場所のみを一致させるようにfind文字列をより具体的にしてください。

エラー：無効な正規表現パターン regex: trueの場合、パターンは正確性とセキュリティについて検証されます。

patchNodeField: invalid or unsafe regex pattern

修正方法：正規表現の構文を確認してください。(a+)+のようなネストされた定量子とReDoSリスクとして(\w|\d)+のような重複する選択肢は拒否されます。パターンを簡略化してください。

---

Auto-Sanitization System

やること

任意のワークフロー更新時に一般的なオペレータ構造の問題を自動的に修正

実行時機：

• n8n_create_workflow
• n8n_update_partial_workflow
• ワークフロー保存操作

修正内容

1. バイナリ演算子（2つの値）

演算子：equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith

修正：singleValueプロパティを削除（バイナリ演算子は2つの値を比較）

前：

{
  "type": "boolean",
  "operation": "equals",
  "singleValue": true  // ❌ 間違い！
}

後（自動）：

{
  "type": "boolean",
  "operation": "equals"
  // singleValue削除 ✅
}

2. ユナリ演算子（1つの値）

演算子：isEmpty, isNotEmpty, true, false

修正：singleValue: trueを追加（ユナリ演算子は単一値をチェック）

前：

{
  "type": "boolean",
  "operation": "isEmpty"
  // singleValue不足 ❌
}

後（自動）：

{
  "type": "boolean",
  "operation": "isEmpty",
  "singleValue": true  // ✅ 追加
}

3. IF/Switch メタデータ

修正：IF v2.2+およびSwitch v3.2+用の完全なconditions.optionsメタデータを追加

修正できないこと

1. 壊れた接続

存在しないノードへの参照

解決方法：n8n_update_partial_workflowでcleanStaleConnections操作を使用

2. ブランチ数の不一致

3つのSwitch規則だが、出力接続は2つのみ

解決方法：不足している接続を追加するか、余分な規則を削除

3. 逆説的な破損状態

APIは破損データを返すが、更新は拒否する

解決方法：手動データベース介入が必要な場合があります

---

False Positives

それは何ですか？

技術的には「間違い」だが、あなたのユースケースでは許容できる検証警告

一般的な誤検知

1. 「エラーハンドリングなし」

警告：エラーハンドリングが構成されていない

許容できる時：

• 失敗が明白なシンプルなワークフロー
• テスト/開発ワークフロー
• 非クリティカルな通知

修正すべき時：重要なデータを処理する本番ワークフロー

2. 「リトライロジックなし」

警告：ノードは失敗時にリトライしない

許容できる時：

• 独自のリトライロジックを持つAPI
• 冪等操作
• 手動トリガーワークフロー

修正すべき時：不安定な外部サービス、本番自動化

3. 「レート制限なし」

警告：APIコール用のレート制限が設定されていない

許容できる時：

• 制限のない内部API
• 低ボリュームワークフロー
• サーバーサイドレート制限を持つAPI

修正すべき時：パブリックAPI、高ボリュームワークフロー

4. 「制限なしクエリ」

警告：LIMITなしのSELECT

許容できる時：

• 既知の小さなデータセット
• 集計クエリ
• 開発/テスト

修正すべき時：大規模なテーブルの本番クエリ

誤検知を減らす

ai-friendlyプロファイルを使用：

validate_node({
  nodeType: "nodes-base.slack",
  config: {...},
  profile: "ai-friendly"  // 誤検知が少ない
})

---

Validation Result Structure

完全なレスポンス

{
  "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フィールドを確認

if (result.valid) {
  // ✅ 設定は有効
} else {
  // ❌ エラーあり - デプロイ前に修正が必須
}

2. 最初にエラーを修正

result.errors.forEach(error => {
  console.log(`Error in ${error.property}: ${error.message}`);
  console.log(`Fix: ${error.fix}`);
});

3. 警告を確認

result.warnings.forEach(warning => {
  console.log(`Warning: ${warning.message}`);
  console.log(`Suggestion: ${warning.suggestion}`);
  // これに対応する必要があるかを決定
});

4. 提案を検討

// オプションの改善
// 必須ではありませんが、ワークフローを強化する可能性

---

Workflow Validation

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. 循環依存関係

{
  "error": "Circular dependency detected: Node A → Node B → Node A"
}

修正：ループを削除するようにワークフローを再構成

3. 複数の開始ノード

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

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

4. 接続されていないノード

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

修正：ノードを接続するか、未使用なら削除

---

Recovery Strategies

戦略1：最初からやり直す

対象：設定が深刻に破損している

ステップ：

1. get_nodeから必須フィールドをメモ
2. 最小限の有効な設定を作成
3. 機能を段階的に追加
4. 追加後に各回検証

戦略2：二分探索

対象：ワークフローは検証されるが、実行が不正確

ステップ：

1. ノードの半分を削除
2. 検証とテスト
3. 機能する場合：問題は削除されたノード内
4. 失敗する場合：問題は残っているノード内
5. 問題が隔離されるまで繰り返し

戦略3：古い接続をクリーン

対象：「ノードが見つかりません」エラー

ステップ：

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

戦略4：オートフィックスを使用

対象：自動的に解決できる検証エラー

ステップ：

// 修正をプレビュー（デフォルト - 適用しない）
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false,
  confidenceThreshold: "medium"  // high, medium, low
})

// 修正を確認してから適用
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

---

Auto-Fix Capabilities

n8n_autofix_workflowツールは次の問題タイプを修正できます：

1. expression-format - 式の=プリフィックスが不足（例：{{ $json.field }} → ={{ $json.field }}）
2. typeversion-correction - サポートされていないtypeVersionsを持つノードをダウングレード
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%未満、手動確認が必須）

// すべての修正をプレビュー
n8n_autofix_workflow({id: "workflow-id"})

// 高い信頼度の修正のみを適用
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true,
  confidenceThreshold: "high"
})

// 特定の修正タイプをターゲット
n8n_autofix_workflow({
  id: "workflow-id",
  fixTypes: ["expression-format", "typeversion-upgrade"],
  applyFixes: true
})

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

---

Best Practices

✅ すべきこと

• 重要な変更後に検証
• エラーメッセージ全文を読む
• エラーを反復的に修正（1回に1つ）
• デプロイ前はruntimeプロファイルを使用
• 成功を仮定する前にvalidフィールドを確認
• オペレータ問題に対して自動サニタイズを信頼
• 要件が不明な場合はget_nodeを使用
• 受け入れた誤検知を文書化

❌ してはいけないこと

• アクティベーション前の検証をスキップ
• すべてのエラーを一度に修正しようとする
• エラーメッセージを無視
• 開発中にstrictプロファイルを使用（ノイズが多すぎる）
• 検証が成功したと仮定（常に結果を確認）
• 自動サニタイズの問題を手動で修正
• 解決されていないエラーでデプロイ
• すべての警告を無視（重要なものもある！）

---

Detailed Guides

包括的なエラーカタログと誤検知の例：

• ERROR_CATALOG.md - エラータイプの完全なリストと例
• FALSE_POSITIVES.md - 警告が許容可能な場合

---

Summary

重要なポイント：

1. 検証は反復的（平均2～3サイクル、23秒+58秒）
2. エラーは修正が必須、警告はオプション
3. 自動サニタイズはオペレータ構造を自動修正
4. runtimeプロファイルを使用してバランスの取れた検証
5. 誤検知が存在します - それを認識することを学ぶ
6. エラーメッセージを読んでください - 修正ガイダンスが含まれています

検証プロセス：

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

関連スキル & ツール：

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