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 — 推奨されていますが、必須ではありません
• deprecated — 古い API／機能を使用しています
• performance — パフォーマンスの問題が発生する可能性があります

例：

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

3. 提案（任意）

あると便利です — ワークフローを改善できる可能性があります

種類：

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

---

検証ループ

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

7,841 件確認されたこのパターン：

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

例

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

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

// ⏱️  23 seconds thinking...

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

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

// ⏱️  58 seconds fixing...

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

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

これは通常のことです！ 複数回の反復をためらう必要はありません。

---

検証プロファイル

作業段階に合ったプロファイルを選択してください。

minimal

用途：編集時の簡易チェック

検証内容：

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

メリット：最速で、最も寛容です
デメリット：問題を見逃す可能性があります

runtime（推奨）

用途：デプロイ前の検証

検証内容：

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

メリット：バランスが良く、実際のエラーを検出します
デメリット：一部のエッジケースを見逃します

ほとんどのユースケースで、このプロファイルを推奨します

ai-friendly

用途：AI が生成した設定

検証内容：

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

メリット：AI ワークフローで不要な警告が減ります
デメリット：問題のある設定が許容される可能性があります

strict

用途：本番環境へのデプロイ、重要なワークフロー

検証内容：

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

メリット：最大限の安全性
デメリット：警告が多く、一部は誤検知です

---

よくあるエラーの種類

1. missing_required

意味：必須フィールドが指定されていません

修正方法：

1. get_node_essentials を使って必須フィールドを確認します
2. 設定に不足しているフィールドを追加します
3. 適切な値を指定します

例：

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

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

2. invalid_value

意味：値が許可された選択肢と一致しません

修正方法：

1. エラーメッセージで許可された値を確認します
2. get_node_essentials を使って選択肢を確認します
3. 有効な値に更新します

例：

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

// Fix
config.operation = "post";  // Use valid operation

3. type_mismatch

意味：フィールドのデータ型が正しくありません

修正方法：

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

例：

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

// Fix
config.limit = 100;  // Number, not string

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}}";  // Add {{}}

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 - correct typo
config.expression = "={{$node['HTTP Request'].json.data}}";

---

自動サニタイズシステム

処理内容

ワークフローを更新するたびに、よくあるオペレーター構造の問題を自動的に修正します

実行される操作：

• 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  // ❌ Wrong!
}

修正後（自動）：

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

2. 単項演算子（1つの値）

演算子：isEmpty、isNotEmpty、true、false

修正内容：singleValue: true を追加します（単項演算子は1つの値を確認します）。

修正前：

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

修正後（自動）：

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

3. IF／Switch メタデータ

修正内容：IF v2.2+ と Switch v3.2+ の完全な conditions.options メタデータを追加します。

修正できないもの

1. 接続の破損

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

解決方法：n8n_update_partial_workflow の cleanStaleConnections 操作を使用します。

2. 分岐数の不一致

Switch のルールは3つあるのに、出力接続は2つしかない

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

3. 矛盾する破損状態

API が破損したデータを返す一方で、更新を拒否する

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

---

誤検知

誤検知とは？

技術的には「誤り」ですが、用途によっては許容できる検証警告です。

よくある誤検知

1. 「エラー処理がない」

警告：エラー処理が設定されていません。

許容できる場合：

• 失敗が明らかなシンプルなワークフロー
• テスト／開発用のワークフロー
• 重要度の低い通知

修正すべき場合：重要なデータを扱う本番ワークフロー

2. 「再試行ロジックがない」

警告：ノードは失敗時に再試行しません。

許容できる場合：

• 独自の再試行ロジックを備えた API
• 冪等な操作
• 手動トリガーのワークフロー

修正すべき場合：不安定な外部サービス、本番環境の自動化

3. 「レート制限がない」

警告：API 呼び出しにレート制限がありません。

許容できる場合：

• 制限のない内部 API
• 少量のワークフロー
• サーバー側でレート制限される API

修正すべき場合：公開 API、大量のワークフロー

4. 「クエリに上限がない」

警告：LIMIT を指定せずに SELECT しています。

許容できる場合：

• 規模が小さいと分かっているデータセット
• 集計クエリ
• 開発／テスト

修正すべき場合：大規模テーブルに対する本番クエリ

誤検知を減らす

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

validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {...},
  profile: "ai-friendly"  // Fewer false positives
})

---

検証結果の構造

完全なレスポンス

{
  "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) {
  // ✅ Configuration is valid
} else {
  // ❌ Has errors - must fix before deployment
}

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}`);
  // Decide if you need to address this
});

4. 提案を検討する

// Optional improvements
// Not required but may enhance workflow

---

ワークフローの検証

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"
}

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

---

復旧方法

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

適用する場合：設定が深刻に破損している

手順：

1. get_node_essentials から必須フィールドを確認します
2. 有効な最小構成を作成します
3. 機能を段階的に追加します
4. 追加のたびに検証します

方法 2：二分探索

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

手順：

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

方法 3：古い接続をクリーンアップする

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

手順：

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

方法 4：自動修正を使用する

適用する場合：演算子の構造エラー

手順：

n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false  // Preview first
})

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

---

ベストプラクティス

✅ すべきこと

• 重要な変更を加えるたびに検証する
• エラーメッセージを最後まで読む
• エラーを一つずつ繰り返し修正する
• デプロイ前には runtime プロファイルを使用する
• 成功したと判断する前に valid フィールドを確認する
• オペレーターに関する問題は自動サニタイズを利用する
• 要件が不明な場合は get_node_essentials を使用する
• 許容する誤検出を記録する

❌ してはいけないこと

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

---

詳細ガイド

エラーの包括的な一覧と誤検出の例については、以下をご覧ください。

• ERROR_CATALOG.md - エラーの種類を例とともに網羅した一覧
• FALSE_POSITIVES.md - 警告を許容できる場合

---

まとめ

重要なポイント：

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 - 必須フィールドを理解する