@awesomate/hosting-mcp 0.12.0 → 0.13.0

package/skill/awesomate-n8n/references/vendor/validation/ERROR_CATALOG.md

@@ -0,0 +1,781 @@
+<!--
+  VENDORED from n8n-builder@d293559 (n8n-validation-expert/ERROR_CATALOG.md) — DO NOT EDIT HERE.
+  Edit the source in ~/Projects/n8n-builder, then re-run:
+    node mcp/scripts/sync-n8n-references.mjs --write
+
+  Awesomate platform overrides — where this file conflicts with
+  ../platform-notes.md, platform-notes wins:
+    - $env is BLOCKED fleet-wide → use {{ $vars.key || 'fallback' }}
+    - Task runners are ON → no $helpers in Code nodes; use HTTP Request nodes
+    - Webhook payloads live at $json.body
+    - saveExecutionProgress must stay false
+-->
+
+# Error Catalog
+
+Comprehensive catalog of n8n configuration errors with real examples and fixes. These are the error shapes you'll see in editor warnings, execution error messages, and when reviewing workflow JSON.
+
+---
+
+## Error Types Overview
+
+Common errors by priority:
+
+| Error Type | Priority | Severity | Editor Fixes on Save |
+|---|---|---|---|
+| missing_required | Highest | Error | ❌ |
+| invalid_value | High | Error | ❌ |
+| type_mismatch | Medium | Error | ❌ |
+| invalid_expression | Medium | Error | ❌ |
+| invalid_reference | Low | Error | ❌ |
+| operator_structure | Lowest | Warning | ✅ |
+
+---
+
+## 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 configuration error**
+
+#### Example 1: Slack Channel Missing
+
+**Error**:
+```
+Problem in node 'Slack'
+Channel name is required (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**: open the node in the editor - required fields are marked and highlighted red when empty. When reviewing JSON, compare against a freshly-added node of the same type.
+
+#### Example 2: HTTP Request Missing URL
+
+**Error**:
+```
+Problem in node 'HTTP Request'
+URL is required (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
+
+**Error**:
+```
+Problem in node 'Postgres'
+SQL query is required (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**:
+```
+Problem in node 'HTTP Request'
+Request body is required when sendBody is true (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**:
+```
+Operation must be one of: post, update, delete, get
+(current: "send")
+```
+
+**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**:
+```
+Method must be one of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
+(current: "FETCH")
+```
+
+**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**:
+```
+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**:
+```
+Resource must be one of: channel, message, user, file
+(current: "Message")
+```
+
+**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**:
+```
+Expected number, got string (property: limit, 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**:
+```
+Expected string, got number (property: channel, 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**:
+```
+Expected boolean, got string (property: sendHeaders, 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**:
+```
+Expected array, got object (property: tags, 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**:
+```
+Expressions must be wrapped in {{}} (property: text, 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**:
+```
+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** (at execution time):
+```
+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** (at execution time):
+```
+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**:
+```
+Node 'Transform Data' does not exist in workflow
+```
+
+**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**:
+```
+Connection references node 'Slack1' which does not exist
+(source: "HTTP Request", target: "Slack1")
+```
+
+**Fix**: Remove the stale entry from the workflow JSON's `connections` object, or delete and re-draw the connection in the editor. Connections are keyed by node **name**, so renames outside the editor break them.
+
+#### Example 3: Renamed Node Not Updated
+
+**Error**:
+```
+Node 'Get Weather' does not exist (did you mean '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**: Slack API can have rate limits and connection issues - no error handling configured.
+
+**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**: External API calls should retry on failure - add `retryOnFail: true, maxTries: 3, waitBetweenTries: 1000` (in the editor: Settings tab → Retry On Fail).
+
+**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**:
+```
+typeVersion 1 is deprecated for Slack node, use version 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**: SELECT without LIMIT can return massive datasets - add LIMIT clause or use pagination.
+
+**Current**:
+```sql
+SELECT * FROM users WHERE active = true
+```
+
+**Fix**:
+```sql
+SELECT * FROM users WHERE active = true LIMIT 1000
+```
+
+---
+
+## Editor-Normalized Structures
+
+### 9. operator_structure
+
+**What it means**: IF/Switch operator structure issues
+
+**Severity**: Warning
+
+**Editor fixes on save**: ✅ YES - the n8n editor normalizes these when the node is saved
+
+**Rare** (matters mainly for hand-written JSON before import)
+
+#### Normalized: Binary Operators
+
+**Wrong** (hand-written JSON):
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals",
+  "singleValue": true  // ❌ Wrong for binary operator
+}
+```
+
+**Correct**:
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals"
+  // singleValue removed ✅
+}
+```
+
+#### Normalized: Unary Operators
+
+**Wrong**:
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty"
+  // Missing singleValue ❌
+}
+```
+
+**Correct**:
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty",
+  "singleValue": true  // ✅ Required
+}
+```
+
+**What you should do**: get these right when hand-writing JSON; for workflows built in the editor, opening and re-saving the node normalizes them.
+
+---
+
+## Recovery Patterns
+
+### Pattern 1: Progressive Configuration
+
+**Problem**: Too many errors at once
+
+**Solution**:
+```javascript
+// Step 1: Minimal valid config - execute to confirm it works
+{
+  resource: "message",
+  operation: "post",
+  channel: "#general",
+  text: "Hello"
+}
+// ✅ Runs
+
+// Step 2: Add features one by one, re-executing after each
+// + attachments → re-execute
+// + blocks → re-execute
+```
+
+### Pattern 2: Error Triage
+
+**Problem**: Multiple errors and warnings pasted at once
+
+**Solution** - sort into three buckets:
+1. **MUST FIX**: errors that block execution (missing fields, invalid values, broken references)
+2. **SHOULD FIX**: warnings (error handling, retries, deprecation)
+3. **OPTIONAL**: suggestions (optimizations, alternatives)
+
+Fix the errors first, one at a time, rechecking between fixes.
+
+### Pattern 3: Compare with a Fresh Node
+
+**Problem**: Don't know what's required
+
+**Solution**: Add a fresh node of the same type in the editor - required fields are marked in the panel, and its exported JSON shows the correct default structure to compare against.
+
+---
+
+## Summary
+
+**Most Common Errors**:
+1. `missing_required` - Check the node panel for marked required fields
+2. `invalid_value` - Check allowed values (case-sensitive)
+3. `type_mismatch` - Use correct data types
+4. `invalid_expression` - Use Expression Syntax skill
+5. `invalid_reference` - Clean stale connections/references
+
+**Editor-Normalized**:
+- `operator_structure` - the editor fixes these on save
+
+**Related Files**:
+- **[SKILL.md](SKILL.md)** - Main guide
+- **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)** - When to ignore warnings
+- **n8n Expression Syntax** - Fix expression errors