@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/n8n-automation/references/validation-expert.md

@@ -0,0 +1,2491 @@
+<!-- Adapted from czlonkowski/n8n-skills (MIT). Source files: SKILL.md, ERROR_CATALOG.md, FALSE_POSITIVES.md -->
+
+# n8n Validation Expert
+
+Expert guide for interpreting and fixing n8n validation errors.
+
+---
+
+## Validation Philosophy
+
+**Validate early, validate often**
+
+Validation is typically iterative:
+
+- Expect validation feedback loops
+- Usually 2-3 validate -> fix cycles
+- Average: 23s thinking about errors, 58s fixing them
+
+**Key insight**: Validation is an iterative process, not one-shot!
+
+---
+
+## Error Severity Levels
+
+### 1. Errors (Must Fix)
+
+**Blocks workflow execution** - Must be resolved before activation
+
+**Types**:
+
+- `missing_required` - Required field not provided
+- `invalid_value` - Value doesn't match allowed options
+- `type_mismatch` - Wrong data type (string instead of number)
+- `invalid_reference` - Referenced node doesn't exist
+- `invalid_expression` - Expression syntax error
+
+**Example**:
+
+```json
+{
+  "type": "missing_required",
+  "property": "channel",
+  "message": "Channel name is required",
+  "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
+}
+```
+
+### 2. Warnings (Should Fix)
+
+**Doesn't block execution** - Workflow can be activated but may have issues
+
+**Types**:
+
+- `best_practice` - Recommended but not required
+- `deprecated` - Using old API/feature
+- `performance` - Potential performance issue
+
+**Example**:
+
+```json
+{
+  "type": "best_practice",
+  "property": "errorHandling",
+  "message": "Slack API can have rate limits",
+  "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
+}
+```
+
+### 3. Suggestions (Optional)
+
+**Nice to have** - Improvements that could enhance workflow
+
+**Types**:
+
+- `optimization` - Could be more efficient
+- `alternative` - Better way to achieve same result
+
+---
+
+## The Validation Loop
+
+### Pattern from Telemetry
+
+**7,841 occurrences** of this pattern:
+
+```
+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)
+```
+
+> **Cross-reference**: See [mcp-tools-expert.md](mcp-tools-expert.md) for `validate_node` and `validate_workflow` tool usage.
+
+### Example
+
+```javascript
+// 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!
+```
+
+**This is normal!** Don't be discouraged by multiple iterations.
+
+---
+
+## Validation Profiles
+
+Choose the right profile for your stage:
+
+### minimal
+
+**Use when**: Quick checks during editing
+
+**Validates**:
+
+- Only required fields
+- Basic structure
+
+**Pros**: Fastest, most permissive
+**Cons**: May miss issues
+
+### runtime (RECOMMENDED)
+
+**Use when**: Pre-deployment validation
+
+**Validates**:
+
+- Required fields
+- Value types
+- Allowed values
+- Basic dependencies
+
+**Pros**: Balanced, catches real errors
+**Cons**: Some edge cases missed
+
+**This is the recommended profile for most use cases**
+
+### ai-friendly
+
+**Use when**: AI-generated configurations
+
+**Validates**:
+
+- Same as runtime
+- Reduces false positives
+- More tolerant of minor issues
+
+**Pros**: Less noisy for AI workflows
+**Cons**: May allow some questionable configs
+
+### strict
+
+**Use when**: Production deployment, critical workflows
+
+**Validates**:
+
+- Everything
+- Best practices
+- Performance concerns
+- Security issues
+
+**Pros**: Maximum safety
+**Cons**: Many warnings, some false positives
+
+---
+
+## Common Error Types
+
+### 1. missing_required
+
+**What it means**: A required field is not provided
+
+**How to fix**:
+
+1. Use `get_node` to see required fields
+2. Add the missing field to your configuration
+3. Provide an appropriate value
+
+> **Cross-reference**: See [node-configuration.md](node-configuration.md) for fixing configuration errors and understanding required fields.
+
+**Example**:
+
+```javascript
+// Error
+{
+  "type": "missing_required",
+  "property": "channel",
+  "message": "Channel name is required"
+}
+
+// Fix
+config.channel = "#general";
+```
+
+### 2. invalid_value
+
+**What it means**: Value doesn't match allowed options
+
+**How to fix**:
+
+1. Check error message for allowed values
+2. Use `get_node` to see options
+3. Update to a valid value
+
+**Example**:
+
+```javascript
+// 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
+
+**What it means**: Wrong data type for field
+
+**How to fix**:
+
+1. Check expected type in error message
+2. Convert value to correct type
+
+**Example**:
+
+```javascript
+// Error
+{
+  "type": "type_mismatch",
+  "property": "limit",
+  "message": "Expected number, got string",
+  "current": "100"
+}
+
+// Fix
+config.limit = 100;  // Number, not string
+```
+
+### 4. invalid_expression
+
+**What it means**: Expression syntax error
+
+**How to fix**:
+
+1. Use n8n Expression Syntax skill
+2. Check for missing `{{}}` or typos
+3. Verify node/field references
+
+**Example**:
+
+```javascript
+// Error
+{
+  "type": "invalid_expression",
+  "property": "text",
+  "message": "Invalid expression: $json.name",
+  "current": "$json.name"
+}
+
+// Fix
+config.text = "={{$json.name}}";  // Add {{}}
+```
+
+### 5. invalid_reference
+
+**What it means**: Referenced node doesn't exist
+
+**How to fix**:
+
+1. Check node name spelling
+2. Verify node exists in workflow
+3. Update reference to correct name
+
+**Example**:
+
+```javascript
+// 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}}";
+```
+
+---
+
+## Validation Result Structure
+
+### Complete Response
+
+```javascript
+{
+  "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
+  }
+}
+```
+
+### How to Read It
+
+#### 1. Check `valid` field
+
+```javascript
+if (result.valid) {
+  // Configuration is valid
+} else {
+  // Has errors - must fix before deployment
+}
+```
+
+#### 2. Fix errors first
+
+```javascript
+result.errors.forEach((error) => {
+  console.log(`Error in ${error.property}: ${error.message}`);
+  console.log(`Fix: ${error.fix}`);
+});
+```
+
+#### 3. Review warnings
+
+```javascript
+result.warnings.forEach((warning) => {
+  console.log(`Warning: ${warning.message}`);
+  console.log(`Suggestion: ${warning.suggestion}`);
+  // Decide if you need to address this
+});
+```
+
+#### 4. Consider suggestions
+
+```javascript
+// Optional improvements
+// Not required but may enhance workflow
+```
+
+---
+
+## Workflow Validation
+
+### validate_workflow (Structure)
+
+**Validates entire workflow**, not just individual nodes
+
+> **Cross-reference**: See [mcp-tools-expert.md](mcp-tools-expert.md) for `validate_workflow` tool parameters and usage patterns.
+
+**Checks**:
+
+1. **Node configurations** - Each node valid
+2. **Connections** - No broken references
+3. **Expressions** - Syntax and references valid
+4. **Flow** - Logical workflow structure
+
+**Example**:
+
+```javascript
+validate_workflow({
+  workflow: {
+    nodes: [...],
+    connections: {...}
+  },
+  options: {
+    validateNodes: true,
+    validateConnections: true,
+    validateExpressions: true,
+    profile: "runtime"
+  }
+})
+```
+
+### Common Workflow Errors
+
+#### 1. Broken Connections
+
+```json
+{
+  "error": "Connection from 'Transform' to 'NonExistent' - target node not found"
+}
+```
+
+**Fix**: Remove stale connection or create missing node
+
+#### 2. Circular Dependencies
+
+```json
+{
+  "error": "Circular dependency detected: Node A -> Node B -> Node A"
+}
+```
+
+**Fix**: Restructure workflow to remove loop
+
+#### 3. Multiple Start Nodes
+
+```json
+{
+  "warning": "Multiple trigger nodes found - only one will execute"
+}
+```
+
+**Fix**: Remove extra triggers or split into separate workflows
+
+#### 4. Disconnected Nodes
+
+```json
+{
+  "warning": "Node 'Transform' is not connected to workflow flow"
+}
+```
+
+**Fix**: Connect node or remove if unused
+
+---
+
+## Recovery Strategies
+
+### Strategy 1: Start Fresh
+
+**When**: Configuration is severely broken
+
+**Steps**:
+
+1. Note required fields from `get_node`
+2. Create minimal valid configuration
+3. Add features incrementally
+4. Validate after each addition
+
+### Strategy 2: Binary Search
+
+**When**: Workflow validates but executes incorrectly
+
+**Steps**:
+
+1. Remove half the nodes
+2. Validate and test
+3. If works: problem is in removed nodes
+4. If fails: problem is in remaining nodes
+5. Repeat until problem isolated
+
+### Strategy 3: Clean Stale Connections
+
+**When**: "Node not found" errors
+
+**Steps**:
+
+```javascript
+n8n_update_partial_workflow({
+  id: "workflow-id",
+  operations: [
+    {
+      type: "cleanStaleConnections",
+    },
+  ],
+});
+```
+
+### Strategy 4: Use Auto-fix
+
+**When**: Operator structure errors
+
+**Steps**:
+
+```javascript
+n8n_autofix_workflow({
+  id: "workflow-id",
+  applyFixes: false, // Preview first
+});
+
+// Review fixes, then apply
+n8n_autofix_workflow({
+  id: "workflow-id",
+  applyFixes: true,
+});
+```
+
+---
+
+## Best Practices
+
+### Do
+
+- Validate after every significant change
+- Read error messages completely
+- Fix errors iteratively (one at a time)
+- Use `runtime` profile for pre-deployment
+- Check `valid` field before assuming success
+- Trust auto-sanitization for operator issues
+- Use `get_node` when unclear about requirements
+- Document false positives you accept
+
+### Don't
+
+- Skip validation before activation
+- Try to fix all errors at once
+- Ignore error messages
+- Use `strict` profile during development (too noisy)
+- Assume validation passed (always check result)
+- Manually fix auto-sanitization issues
+- Deploy with unresolved errors
+- Ignore all warnings (some are important!)
+
+---
+
+## Summary
+
+**Key Points**:
+
+1. **Validation is iterative** (avg 2-3 cycles, 23s + 58s)
+2. **Errors must be fixed**, warnings are optional
+3. **Auto-sanitization** fixes operator structures automatically
+4. **Use runtime profile** for balanced validation
+5. **False positives exist** - learn to recognize them
+6. **Read error messages** - they contain fix guidance
+
+**Validation Process**:
+
+1. Validate -> Read errors -> Fix -> Validate again
+2. Repeat until valid (usually 2-3 iterations)
+3. Review warnings and decide if acceptable
+4. Deploy with confidence
+
+**Related Skills**:
+
+- n8n MCP Tools Expert - Use validation tools correctly
+- n8n Expression Syntax - Fix expression errors
+- n8n Node Configuration - Understand required fields
+
+---
+
+# Error Catalog
+
+Comprehensive catalog of n8n validation errors with real examples and fixes.
+
+---
+
+## Error Types Overview
+
+Common validation errors by priority:
+
+| Error Type         | Priority | Severity | Auto-Fix |
+| ------------------ | -------- | -------- | -------- |
+| missing_required   | Highest  | Error    | No       |
+| invalid_value      | High     | Error    | No       |
+| type_mismatch      | Medium   | Error    | No       |
+| invalid_expression | Medium   | Error    | No       |
+| invalid_reference  | Low      | Error    | No       |
+| operator_structure | Lowest   | Warning  | Yes      |
+
+---
+
+## Errors (Must Fix)
+
+### 1. missing_required
+
+**What it means**: Required field is not provided in node configuration
+
+**When it occurs**:
+
+- Creating new nodes without all required fields
+- Copying configurations between different operations
+- Switching operations that have different requirements
+
+**Most common validation error**
+
+> **Cross-reference**: See [node-configuration.md](node-configuration.md) for understanding required fields per node type.
+
+#### Example 1: Slack Channel Missing
+
+**Error**:
+
+```json
+{
+  "type": "missing_required",
+  "property": "channel",
+  "message": "Channel name is required",
+  "node": "Slack",
+  "path": "parameters.channel"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post"
+  // Missing: channel
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general"  // Added required field
+}
+```
+
+**How to identify required fields**:
+
+```javascript
+// Use get_node to see what's required
+const info = get_node({
+  nodeType: "nodes-base.slack",
+});
+// Check properties marked as "required": true
+```
+
+#### Example 2: HTTP Request Missing URL
+
+**Error**:
+
+```json
+{
+  "type": "missing_required",
+  "property": "url",
+  "message": "URL is required for HTTP Request",
+  "node": "HTTP Request",
+  "path": "parameters.url"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "method": "GET",
+  "authentication": "none"
+  // Missing: url
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "method": "GET",
+  "authentication": "none",
+  "url": "https://api.example.com/data"  // Added
+}
+```
+
+#### Example 3: Database Query Missing Connection
+
+**Error**:
+
+```json
+{
+  "type": "missing_required",
+  "property": "query",
+  "message": "SQL query is required",
+  "node": "Postgres",
+  "path": "parameters.query"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "operation": "executeQuery"
+  // Missing: query
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "operation": "executeQuery",
+  "query": "SELECT * FROM users WHERE active = true"  // Added
+}
+```
+
+#### Example 4: Conditional Fields
+
+**Error**:
+
+```json
+{
+  "type": "missing_required",
+  "property": "body",
+  "message": "Request body is required when sendBody is true",
+  "node": "HTTP Request",
+  "path": "parameters.body"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/create",
+  "sendBody": true
+  // Missing: body (required when sendBody=true)
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/create",
+  "sendBody": true,
+  "body": {
+    "contentType": "json",
+    "content": {
+      "name": "John",
+      "email": "john@example.com"
+    }
+  }  // Added conditional required field
+}
+```
+
+---
+
+### 2. invalid_value
+
+**What it means**: Provided value doesn't match allowed options or format
+
+**When it occurs**:
+
+- Using wrong enum value
+- Typos in operation names
+- Invalid format for specialized fields (emails, URLs, channels)
+
+**Second most common error**
+
+#### Example 1: Invalid Operation
+
+**Error**:
+
+```json
+{
+  "type": "invalid_value",
+  "property": "operation",
+  "message": "Operation must be one of: post, update, delete, get",
+  "current": "send",
+  "allowed": ["post", "update", "delete", "get"]
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "send"  // Invalid - should be "post"
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post"  // Use valid operation
+}
+```
+
+#### Example 2: Invalid HTTP Method
+
+**Error**:
+
+```json
+{
+  "type": "invalid_value",
+  "property": "method",
+  "message": "Method must be one of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS",
+  "current": "FETCH",
+  "allowed": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "method": "FETCH",  // Invalid
+  "url": "https://api.example.com"
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "method": "GET",  // Use valid HTTP method
+  "url": "https://api.example.com"
+}
+```
+
+#### Example 3: Invalid Channel Format
+
+**Error**:
+
+```json
+{
+  "type": "invalid_value",
+  "property": "channel",
+  "message": "Channel name must start with # and be lowercase (e.g., #general)",
+  "current": "General"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "General"  // Wrong format
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general"  // Correct format
+}
+```
+
+#### Example 4: Invalid Enum with Case Sensitivity
+
+**Error**:
+
+```json
+{
+  "type": "invalid_value",
+  "property": "resource",
+  "message": "Resource must be one of: channel, message, user, file",
+  "current": "Message",
+  "allowed": ["channel", "message", "user", "file"]
+}
+```
+
+**Note**: Enums are case-sensitive!
+
+**Broken Configuration**:
+
+```javascript
+{
+  "resource": "Message",  // Capital M
+  "operation": "post"
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "resource": "message",  // Lowercase
+  "operation": "post"
+}
+```
+
+---
+
+### 3. type_mismatch
+
+**What it means**: Value is wrong data type (string instead of number, etc.)
+
+**When it occurs**:
+
+- Hardcoding values that should be numbers
+- Using expressions where literals are expected
+- JSON serialization issues
+
+**Common error**
+
+#### Example 1: String Instead of Number
+
+**Error**:
+
+```json
+{
+  "type": "type_mismatch",
+  "property": "limit",
+  "message": "Expected number, got string",
+  "expected": "number",
+  "current": "100"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "operation": "executeQuery",
+  "query": "SELECT * FROM users",
+  "limit": "100"  // String
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "operation": "executeQuery",
+  "query": "SELECT * FROM users",
+  "limit": 100  // Number
+}
+```
+
+#### Example 2: Number Instead of String
+
+**Error**:
+
+```json
+{
+  "type": "type_mismatch",
+  "property": "channel",
+  "message": "Expected string, got number",
+  "expected": "string",
+  "current": 12345
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": 12345  // Number (even if channel ID)
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general"  // String (channel name, not ID)
+}
+```
+
+#### Example 3: Boolean as String
+
+**Error**:
+
+```json
+{
+  "type": "type_mismatch",
+  "property": "sendHeaders",
+  "message": "Expected boolean, got string",
+  "expected": "boolean",
+  "current": "true"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "method": "GET",
+  "url": "https://api.example.com",
+  "sendHeaders": "true"  // String "true"
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "method": "GET",
+  "url": "https://api.example.com",
+  "sendHeaders": true  // Boolean true
+}
+```
+
+#### Example 4: Object Instead of Array
+
+**Error**:
+
+```json
+{
+  "type": "type_mismatch",
+  "property": "tags",
+  "message": "Expected array, got object",
+  "expected": "array",
+  "current": { "tag": "important" }
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "name": "New Channel",
+  "tags": {"tag": "important"}  // Object
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "name": "New Channel",
+  "tags": ["important", "alerts"]  // Array
+}
+```
+
+---
+
+### 4. invalid_expression
+
+**What it means**: n8n expression has syntax errors or invalid references
+
+**When it occurs**:
+
+- Missing `{{}}` around expressions
+- Typos in variable names
+- Referencing non-existent nodes or fields
+- Invalid JavaScript syntax in expressions
+
+**Moderately common**
+
+**Related**: See **n8n Expression Syntax** skill for comprehensive expression guidance
+
+#### Example 1: Missing Curly Braces
+
+**Error**:
+
+```json
+{
+  "type": "invalid_expression",
+  "property": "text",
+  "message": "Expressions must be wrapped in {{}}",
+  "current": "$json.name"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",
+  "text": "$json.name"  // Missing {{}}
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",
+  "text": "={{$json.name}}"  // Wrapped in {{}}
+}
+```
+
+#### Example 2: Invalid Node Reference
+
+**Error**:
+
+```json
+{
+  "type": "invalid_expression",
+  "property": "value",
+  "message": "Referenced node 'HTTP Requets' does not exist",
+  "current": "={{$node['HTTP Requets'].json.data}}"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "field": "data",
+  "value": "={{$node['HTTP Requets'].json.data}}"  // Typo in node name
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "field": "data",
+  "value": "={{$node['HTTP Request'].json.data}}"  // Correct node name
+}
+```
+
+#### Example 3: Invalid Property Access
+
+**Error**:
+
+```json
+{
+  "type": "invalid_expression",
+  "property": "text",
+  "message": "Cannot access property 'user' of undefined",
+  "current": "={{$json.data.user.name}}"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "text": "={{$json.data.user.name}}"  // Structure doesn't exist
+}
+```
+
+**Fix** (with safe navigation):
+
+```javascript
+{
+  "text": "={{$json.data?.user?.name || 'Unknown'}}"  // Safe navigation + fallback
+}
+```
+
+#### Example 4: Webhook Data Access Error
+
+**Error**:
+
+```json
+{
+  "type": "invalid_expression",
+  "property": "value",
+  "message": "Property 'email' not found in $json",
+  "current": "={{$json.email}}"
+}
+```
+
+**Common Gotcha**: Webhook data is under `.body`!
+
+**Broken Configuration**:
+
+```javascript
+{
+  "field": "email",
+  "value": "={{$json.email}}"  // Missing .body
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "field": "email",
+  "value": "={{$json.body.email}}"  // Webhook data under .body
+}
+```
+
+---
+
+### 5. invalid_reference
+
+**What it means**: Configuration references a node that doesn't exist in the workflow
+
+**When it occurs**:
+
+- Node was renamed or deleted
+- Typo in node name
+- Copy-pasting from another workflow
+
+**Less common error**
+
+#### Example 1: Deleted Node Reference
+
+**Error**:
+
+```json
+{
+  "type": "invalid_reference",
+  "property": "expression",
+  "message": "Node 'Transform Data' does not exist in workflow",
+  "referenced_node": "Transform Data"
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "value": "={{$node['Transform Data'].json.result}}"  // Node deleted
+}
+```
+
+**Fix**:
+
+```javascript
+// Option 1: Update to existing node
+{
+  "value": "={{$node['Set'].json.result}}"
+}
+
+// Option 2: Remove expression if not needed
+{
+  "value": "default_value"
+}
+```
+
+#### Example 2: Connection to Non-Existent Node
+
+**Error**:
+
+```json
+{
+  "type": "invalid_reference",
+  "message": "Connection references node 'Slack1' which does not exist",
+  "source": "HTTP Request",
+  "target": "Slack1"
+}
+```
+
+**Fix**: Use `cleanStaleConnections` operation:
+
+```javascript
+n8n_update_partial_workflow({
+  id: "workflow-id",
+  operations: [
+    {
+      type: "cleanStaleConnections",
+    },
+  ],
+});
+```
+
+#### Example 3: Renamed Node Not Updated
+
+**Error**:
+
+```json
+{
+  "type": "invalid_reference",
+  "property": "expression",
+  "message": "Node 'Get Weather' does not exist (did you mean 'Weather API'?)",
+  "referenced_node": "Get Weather",
+  "suggestions": ["Weather API"]
+}
+```
+
+**Broken Configuration**:
+
+```javascript
+{
+  "value": "={{$node['Get Weather'].json.temperature}}"  // Old name
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "value": "={{$node['Weather API'].json.temperature}}"  // Current name
+}
+```
+
+---
+
+## Warnings (Should Fix)
+
+### 6. best_practice
+
+**What it means**: Configuration works but doesn't follow best practices
+
+**Severity**: Warning (doesn't block execution)
+
+**When acceptable**: Development, testing, simple workflows
+
+**When to fix**: Production workflows, critical operations
+
+#### Example 1: Missing Error Handling
+
+**Warning**:
+
+```json
+{
+  "type": "best_practice",
+  "property": "onError",
+  "message": "Slack API can have rate limits and connection issues",
+  "suggestion": "Add error handling: onError: 'continueRegularOutput'"
+}
+```
+
+**Current Configuration**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#alerts"
+  // No error handling
+}
+```
+
+**Recommended Fix**:
+
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#alerts",
+  "continueOnFail": true,
+  "retryOnFail": true,
+  "maxTries": 3
+}
+```
+
+#### Example 2: No Retry Logic
+
+**Warning**:
+
+```json
+{
+  "type": "best_practice",
+  "property": "retryOnFail",
+  "message": "External API calls should retry on failure",
+  "suggestion": "Add retryOnFail: true, maxTries: 3, waitBetweenTries: 1000"
+}
+```
+
+**When to ignore**: Idempotent operations, APIs with their own retry logic
+
+**When to fix**: Flaky external services, production automation
+
+---
+
+### 7. deprecated
+
+**What it means**: Using old API version or deprecated feature
+
+**Severity**: Warning (still works but may stop working in future)
+
+**When to fix**: Always (eventually)
+
+#### Example 1: Old typeVersion
+
+**Warning**:
+
+```json
+{
+  "type": "deprecated",
+  "property": "typeVersion",
+  "message": "typeVersion 1 is deprecated for Slack node, use version 2",
+  "current": 1,
+  "recommended": 2
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "type": "n8n-nodes-base.slack",
+  "typeVersion": 2,  // Updated
+  // May need to update configuration for new version
+}
+```
+
+---
+
+### 8. performance
+
+**What it means**: Configuration may cause performance issues
+
+**Severity**: Warning
+
+**When to fix**: High-volume workflows, large datasets
+
+#### Example 1: Unbounded Query
+
+**Warning**:
+
+```json
+{
+  "type": "performance",
+  "property": "query",
+  "message": "SELECT without LIMIT can return massive datasets",
+  "suggestion": "Add LIMIT clause or use pagination"
+}
+```
+
+**Current**:
+
+```sql
+SELECT * FROM users WHERE active = true
+```
+
+**Fix**:
+
+```sql
+SELECT * FROM users WHERE active = true LIMIT 1000
+```
+
+---
+
+## Auto-Sanitization Fixes
+
+### 9. operator_structure
+
+**What it means**: IF/Switch operator structure issues
+
+**Severity**: Warning
+
+**Auto-Fix**: YES - Fixed automatically on workflow save
+
+**Rare** (mostly auto-fixed)
+
+#### Fixed Automatically: Binary Operators
+
+**Before** (you create this):
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals",
+  "singleValue": true  // Wrong for binary operator
+}
+```
+
+**After** (auto-sanitization fixes it):
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals"
+  // singleValue removed
+}
+```
+
+**You don't need to do anything** - this is fixed on save!
+
+#### Fixed Automatically: Unary Operators
+
+**Before**:
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty"
+  // Missing singleValue
+}
+```
+
+**After**:
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty",
+  "singleValue": true  // Added automatically
+}
+```
+
+**What you should do**: Trust auto-sanitization, don't manually fix these!
+
+---
+
+## Recovery Patterns
+
+### Pattern 1: Progressive Validation
+
+**Problem**: Too many errors at once
+
+**Solution**:
+
+```javascript
+// Step 1: Minimal valid config
+let config = {
+  resource: "message",
+  operation: "post",
+  channel: "#general",
+  text: "Hello"
+};
+
+validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"});
+// Valid
+
+// Step 2: Add features one by one
+config.attachments = [...];
+validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"});
+
+config.blocks = [...];
+validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"});
+```
+
+### Pattern 2: Error Triage
+
+**Problem**: Multiple errors
+
+**Solution**:
+
+```javascript
+const result = validate_node_operation({...});
+
+// 1. Fix errors (must fix)
+result.errors.forEach(error => {
+  console.log(`MUST FIX: ${error.property} - ${error.message}`);
+});
+
+// 2. Review warnings (should fix)
+result.warnings.forEach(warning => {
+  console.log(`SHOULD FIX: ${warning.property} - ${warning.message}`);
+});
+
+// 3. Consider suggestions (optional)
+result.suggestions.forEach(sug => {
+  console.log(`OPTIONAL: ${sug.message}`);
+});
+```
+
+### Pattern 3: Use get_node
+
+**Problem**: Don't know what's required
+
+**Solution**:
+
+```javascript
+// Before configuring, check requirements
+const info = get_node({
+  nodeType: "nodes-base.slack",
+});
+
+// Look for required fields
+info.properties.forEach((prop) => {
+  if (prop.required) {
+    console.log(`Required: ${prop.name} (${prop.type})`);
+  }
+});
+```
+
+---
+
+## Error Frequency Summary
+
+**Most Common Errors**:
+
+1. `missing_required` (45%) - Always check get_node
+2. `invalid_value` (28%) - Check allowed values
+3. `type_mismatch` (12%) - Use correct data types
+4. `invalid_expression` (8%) - Use Expression Syntax skill
+5. `invalid_reference` (5%) - Clean stale connections
+
+**Auto-Fixed**:
+
+- `operator_structure` - Trust auto-sanitization!
+
+---
+
+# False Positives Guide
+
+When validation warnings are acceptable and how to handle them.
+
+---
+
+## What Are False Positives?
+
+**Definition**: Validation warnings that are technically "issues" but acceptable in your specific use case.
+
+**Key insight**: Not all warnings need to be fixed!
+
+Many warnings are context-dependent:
+
+- ~40% of warnings are acceptable in specific use cases
+- Using `ai-friendly` profile reduces false positives by 60%
+
+---
+
+## Philosophy
+
+### Good Practice
+
+```
+1. Run validation with 'runtime' profile
+2. Fix all ERRORS
+3. Review each WARNING
+4. Decide if acceptable for your use case
+5. Document why you accepted it
+6. Deploy with confidence
+```
+
+### Bad Practice
+
+```
+1. Ignore all warnings blindly
+2. Use 'minimal' profile to avoid warnings
+3. Deploy without understanding risks
+```
+
+---
+
+## Common False Positives
+
+### 1. Missing Error Handling
+
+**Warning**:
+
+```json
+{
+  "type": "best_practice",
+  "message": "No error handling configured",
+  "suggestion": "Add continueOnFail: true and retryOnFail: true"
+}
+```
+
+#### When Acceptable
+
+**Development/Testing Workflows**
+
+```javascript
+// Testing workflow - failures are obvious
+{
+  "name": "Test Slack Integration",
+  "nodes": [{
+    "type": "n8n-nodes-base.slack",
+    "parameters": {
+      "resource": "message",
+      "operation": "post",
+      "channel": "#test"
+      // No error handling - OK for testing
+    }
+  }]
+}
+```
+
+**Reasoning**: You WANT to see failures during testing.
+
+**Non-Critical Notifications**
+
+```javascript
+// Nice-to-have notification
+{
+  "name": "Optional Slack Notification",
+  "parameters": {
+    "channel": "#general",
+    "text": "FYI: Process completed"
+    // If this fails, no big deal
+  }
+}
+```
+
+**Reasoning**: Notification failure doesn't affect core functionality.
+
+**Manual Trigger Workflows**
+
+```javascript
+// Manual workflow - user is watching
+{
+  "nodes": [{
+    "type": "n8n-nodes-base.webhook",
+    "parameters": {
+      "path": "manual-test"
+      // No error handling - user will retry manually
+    }
+  }]
+}
+```
+
+**Reasoning**: User is present to see and handle errors.
+
+#### When to Fix
+
+**Production Automation**
+
+```javascript
+// BAD: Critical workflow without error handling
+{
+  "name": "Process Customer Orders",
+  "nodes": [{
+    "type": "n8n-nodes-base.postgres",
+    "parameters": {
+      "query": "INSERT INTO orders..."
+      // Should have error handling!
+    }
+  }]
+}
+```
+
+**Fix**:
+
+```javascript
+{
+  "parameters": {
+    "query": "INSERT INTO orders...",
+    "continueOnFail": true,
+    "retryOnFail": true,
+    "maxTries": 3,
+    "waitBetweenTries": 1000
+  }
+}
+```
+
+**Critical Integrations**
+
+```javascript
+// BAD: Payment processing without error handling
+{
+  "name": "Process Payment",
+  "type": "n8n-nodes-base.stripe"
+  // Payment failures MUST be handled!
+}
+```
+
+---
+
+### 2. No Retry Logic
+
+**Warning**:
+
+```json
+{
+  "type": "best_practice",
+  "message": "External API calls should retry on failure",
+  "suggestion": "Add retryOnFail: true with exponential backoff"
+}
+```
+
+#### When Acceptable
+
+**APIs with Built-in Retry**
+
+```javascript
+// Stripe has its own retry mechanism
+{
+  "type": "n8n-nodes-base.stripe",
+  "parameters": {
+    "resource": "charge",
+    "operation": "create"
+    // Stripe SDK retries automatically
+  }
+}
+```
+
+**Idempotent Operations**
+
+```javascript
+// GET request - safe to retry manually if needed
+{
+  "method": "GET",
+  "url": "https://api.example.com/status"
+  // Read-only, no side effects
+}
+```
+
+**Local/Internal Services**
+
+```javascript
+// Internal API with high reliability
+{
+  "url": "http://localhost:3000/process"
+  // Local service, failures are rare and obvious
+}
+```
+
+#### When to Fix
+
+**Flaky External APIs**
+
+```javascript
+// BAD: Known unreliable API without retries
+{
+  "url": "https://unreliable-api.com/data"
+  // Should retry!
+}
+
+// GOOD:
+{
+  "url": "https://unreliable-api.com/data",
+  "retryOnFail": true,
+  "maxTries": 3,
+  "waitBetweenTries": 2000
+}
+```
+
+**Non-Idempotent Operations**
+
+```javascript
+// BAD: POST without retry - may lose data
+{
+  "method": "POST",
+  "url": "https://api.example.com/create"
+  // Could timeout and lose data
+}
+```
+
+---
+
+### 3. Missing Rate Limiting
+
+**Warning**:
+
+```json
+{
+  "type": "best_practice",
+  "message": "API may have rate limits",
+  "suggestion": "Add rate limiting or batch requests"
+}
+```
+
+#### When Acceptable
+
+**Internal APIs**
+
+```javascript
+// Internal microservice - no rate limits
+{
+  "url": "http://internal-api/process"
+  // Company controls both ends
+}
+```
+
+**Low-Volume Workflows**
+
+```javascript
+// Runs once per day
+{
+  "trigger": {
+    "type": "n8n-nodes-base.cron",
+    "parameters": {
+      "mode": "everyDay",
+      "hour": 9
+    }
+  },
+  "nodes": [{
+    "type": "n8n-nodes-base.httpRequest",
+    "parameters": {
+      "url": "https://api.example.com/daily-report"
+      // Once per day = no rate limit concerns
+    }
+  }]
+}
+```
+
+**APIs with Server-Side Limits**
+
+```javascript
+// API returns 429 and n8n handles it
+{
+  "url": "https://api.example.com/data",
+  "options": {
+    "response": {
+      "response": {
+        "neverError": false  // Will error on 429
+      }
+    }
+  },
+  "retryOnFail": true  // Retry on 429
+}
+```
+
+#### When to Fix
+
+**High-Volume Public APIs**
+
+```javascript
+// BAD: Loop hitting rate-limited API
+{
+  "nodes": [{
+    "type": "n8n-nodes-base.splitInBatches",
+    "parameters": {
+      "batchSize": 100
+    }
+  }, {
+    "type": "n8n-nodes-base.httpRequest",
+    "parameters": {
+      "url": "https://api.github.com/..."
+      // GitHub has strict rate limits!
+    }
+  }]
+}
+
+// GOOD: Add rate limiting
+{
+  "type": "n8n-nodes-base.httpRequest",
+  "parameters": {
+    "url": "https://api.github.com/...",
+    "options": {
+      "batching": {
+        "batch": {
+          "batchSize": 10,
+          "batchInterval": 1000  // 1 second between batches
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+### 4. Unbounded Database Queries
+
+**Warning**:
+
+```json
+{
+  "type": "performance",
+  "message": "SELECT without LIMIT can return massive datasets",
+  "suggestion": "Add LIMIT clause or use pagination"
+}
+```
+
+#### When Acceptable
+
+**Small Known Datasets**
+
+```javascript
+// Config table with ~10 rows
+{
+  "query": "SELECT * FROM app_config"
+  // Known to be small, no LIMIT needed
+}
+```
+
+**Aggregation Queries**
+
+```javascript
+// COUNT/SUM operations
+{
+  "query": "SELECT COUNT(*) as total FROM users WHERE active = true"
+  // Aggregation, not returning rows
+}
+```
+
+**Development/Testing**
+
+```javascript
+// Testing with small dataset
+{
+  "query": "SELECT * FROM test_users"
+  // Test database has 5 rows
+}
+```
+
+#### When to Fix
+
+**Production Queries on Large Tables**
+
+```javascript
+// BAD: User table could have millions of rows
+{
+  "query": "SELECT * FROM users"
+  // Could return millions of rows!
+}
+
+// GOOD: Add LIMIT
+{
+  "query": "SELECT * FROM users LIMIT 1000"
+}
+
+// BETTER: Use pagination
+{
+  "query": "SELECT * FROM users WHERE id > {{$json.lastId}} LIMIT 1000"
+}
+```
+
+---
+
+### 5. Missing Input Validation
+
+**Warning**:
+
+```json
+{
+  "type": "best_practice",
+  "message": "Webhook doesn't validate input data",
+  "suggestion": "Add IF node to validate required fields"
+}
+```
+
+#### When Acceptable
+
+**Internal Webhooks**
+
+```javascript
+// Webhook from your own backend
+{
+  "type": "n8n-nodes-base.webhook",
+  "parameters": {
+    "path": "internal-trigger"
+    // Your backend already validates
+  }
+}
+```
+
+**Trusted Sources**
+
+```javascript
+// Webhook from Stripe (cryptographically signed)
+{
+  "type": "n8n-nodes-base.webhook",
+  "parameters": {
+    "path": "stripe-webhook",
+    "authentication": "headerAuth"
+    // Stripe signature validates authenticity
+  }
+}
+```
+
+#### When to Fix
+
+**Public Webhooks**
+
+```javascript
+// BAD: Public webhook without validation
+{
+  "type": "n8n-nodes-base.webhook",
+  "parameters": {
+    "path": "public-form-submit"
+    // Anyone can send anything!
+  }
+}
+
+// GOOD: Add validation
+{
+  "nodes": [
+    {
+      "name": "Webhook",
+      "type": "n8n-nodes-base.webhook"
+    },
+    {
+      "name": "Validate Input",
+      "type": "n8n-nodes-base.if",
+      "parameters": {
+        "conditions": {
+          "boolean": [
+            {
+              "value1": "={{$json.body.email}}",
+              "operation": "isNotEmpty"
+            },
+            {
+              "value1": "={{$json.body.email}}",
+              "operation": "regex",
+              "value2": "^[^@]+@[^@]+\\.[^@]+$"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+---
+
+### 6. Hardcoded Credentials
+
+**Warning**:
+
+```json
+{
+  "type": "security",
+  "message": "Credentials should not be hardcoded",
+  "suggestion": "Use n8n credential system"
+}
+```
+
+#### When Acceptable
+
+**Public APIs (No Auth)**
+
+```javascript
+// Truly public API with no secrets
+{
+  "url": "https://api.ipify.org"
+  // No credentials needed
+}
+```
+
+**Demo/Example Workflows**
+
+```javascript
+// Example workflow in documentation
+{
+  "url": "https://example.com/api",
+  "headers": {
+    "Authorization": "Bearer DEMO_TOKEN"
+  }
+  // Clearly marked as example
+}
+```
+
+#### When to Fix (Always!)
+
+**Real Credentials**
+
+```javascript
+// BAD: Real API key in workflow
+{
+  "headers": {
+    "Authorization": "Bearer sk_live_abc123..."
+  }
+  // NEVER hardcode real credentials!
+}
+
+// GOOD: Use credentials system
+{
+  "authentication": "headerAuth",
+  "credentials": {
+    "headerAuth": {
+      "id": "credential-id",
+      "name": "My API Key"
+    }
+  }
+}
+```
+
+---
+
+## Validation Profile Strategies
+
+### Strategy 1: Progressive Strictness
+
+**Development**:
+
+```javascript
+validate_node({
+  nodeType: "nodes-base.slack",
+  config,
+  profile: "ai-friendly", // Fewer warnings during development
+});
+```
+
+**Pre-Production**:
+
+```javascript
+validate_node({
+  nodeType: "nodes-base.slack",
+  config,
+  profile: "runtime", // Balanced validation
+});
+```
+
+**Production Deployment**:
+
+```javascript
+validate_node({
+  nodeType: "nodes-base.slack",
+  config,
+  profile: "strict", // All warnings, review each one
+});
+```
+
+### Strategy 2: Profile by Workflow Type
+
+**Quick Automations**:
+
+- Profile: `ai-friendly`
+- Accept: Most warnings
+- Fix: Only errors + security warnings
+
+**Business-Critical Workflows**:
+
+- Profile: `strict`
+- Accept: Very few warnings
+- Fix: Everything possible
+
+**Integration Testing**:
+
+- Profile: `minimal`
+- Accept: All warnings (just testing connections)
+- Fix: Only errors that prevent execution
+
+---
+
+## Decision Framework
+
+### Should I Fix This Warning?
+
+```
++----------------------------------+
+| Is it a SECURITY warning?        |
++----------------------------------+
+| YES -> Always fix                |
+| NO  -> Continue                  |
++----------------------------------+
+         |
++----------------------------------+
+| Is this a production workflow?   |
++----------------------------------+
+| YES -> Continue                  |
+| NO  -> Probably acceptable       |
++----------------------------------+
+         |
++----------------------------------+
+| Does it handle critical data?    |
++----------------------------------+
+| YES -> Fix the warning           |
+| NO  -> Continue                  |
++----------------------------------+
+         |
++----------------------------------+
+| Is there a known workaround?     |
++----------------------------------+
+| YES -> Acceptable if documented  |
+| NO  -> Fix the warning           |
++----------------------------------+
+```
+
+---
+
+## Documentation Template
+
+When accepting a warning, document why:
+
+```javascript
+// workflows/customer-notifications.json
+
+{
+  "nodes": [{
+    "name": "Send Slack Notification",
+    "type": "n8n-nodes-base.slack",
+    "parameters": {
+      "channel": "#notifications"
+      // ACCEPTED WARNING: No error handling
+      // Reason: Non-critical notification, failures are acceptable
+      // Reviewed: 2025-10-20
+      // Reviewer: Engineering Team
+    }
+  }]
+}
+```
+
+---
+
+## Known n8n Issues
+
+### Issue #304: IF Node Metadata Warning
+
+**Warning**:
+
+```json
+{
+  "type": "metadata_incomplete",
+  "message": "IF node missing conditions.options metadata",
+  "node": "IF"
+}
+```
+
+**Status**: False positive for IF v2.2+
+
+**Why it occurs**: Auto-sanitization adds metadata, but validation runs before sanitization
+
+**What to do**: Ignore - metadata is added on save
+
+### Issue #306: Switch Branch Count
+
+**Warning**:
+
+```json
+{
+  "type": "configuration_mismatch",
+  "message": "Switch has 3 rules but 4 output connections",
+  "node": "Switch"
+}
+```
+
+**Status**: False positive when using "fallback" mode
+
+**Why it occurs**: Fallback creates extra output
+
+**What to do**: Ignore if using fallback intentionally
+
+### Issue #338: Credential Validation in Test Mode
+
+**Warning**:
+
+```json
+{
+  "type": "credentials_invalid",
+  "message": "Cannot validate credentials without execution context"
+}
+```
+
+**Status**: False positive during static validation
+
+**Why it occurs**: Credentials validated at runtime, not build time
+
+**What to do**: Ignore - credentials are validated when workflow runs
+
+---
+
+## False Positives Summary
+
+### Always Fix
+
+- Security warnings
+- Hardcoded credentials
+- SQL injection risks
+- Production workflow errors
+
+### Usually Fix
+
+- Error handling (production)
+- Retry logic (external APIs)
+- Input validation (public webhooks)
+- Rate limiting (high volume)
+
+### Often Acceptable
+
+- Error handling (dev/test)
+- Retry logic (internal APIs)
+- Rate limiting (low volume)
+- Query limits (small datasets)
+
+### Always Acceptable
+
+- Known n8n issues (#304, #306, #338)
+- Auto-sanitization warnings
+- Metadata completeness (auto-fixed)
+
+**Golden Rule**: If you accept a warning, document WHY.
+
+---
+
+# Auto-Sanitization Behavior
+
+## What It Does
+
+**Automatically fixes common operator structure issues** on ANY workflow update
+
+**Runs when**:
+
+- `n8n_create_workflow`
+- `n8n_update_partial_workflow`
+- Any workflow save operation
+
+## What It Fixes
+
+### 1. Binary Operators (Two Values)
+
+**Operators**: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith
+
+**Fix**: Removes `singleValue` property (binary operators compare two values)
+
+**Before**:
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals",
+  "singleValue": true  // Wrong!
+}
+```
+
+**After** (automatic):
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals"
+  // singleValue removed
+}
+```
+
+### 2. Unary Operators (One Value)
+
+**Operators**: isEmpty, isNotEmpty, true, false
+
+**Fix**: Adds `singleValue: true` (unary operators check single value)
+
+**Before**:
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty"
+  // Missing singleValue
+}
+```
+
+**After** (automatic):
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty",
+  "singleValue": true  // Added
+}
+```
+
+### 3. IF/Switch Metadata
+
+**Fix**: Adds complete `conditions.options` metadata for IF v2.2+ and Switch v3.2+
+
+## What It CANNOT Fix
+
+### 1. Broken Connections
+
+References to non-existent nodes
+
+**Solution**: Use `cleanStaleConnections` operation in `n8n_update_partial_workflow`
+
+### 2. Branch Count Mismatches
+
+3 Switch rules but only 2 output connections
+
+**Solution**: Add missing connections or remove extra rules
+
+### 3. Paradoxical Corrupt States
+
+API returns corrupt data but rejects updates
+
+**Solution**: May require manual database intervention
+
+---
+
+## Cross-References
+
+- **[mcp-tools-expert.md](mcp-tools-expert.md)** - `validate_node` and `validate_workflow` tool parameters, usage patterns, and MCP integration
+- **[node-configuration.md](node-configuration.md)** - Required fields per node type, fixing configuration errors, and understanding node properties