Error Handling & Troubleshooting¶

Comprehensive guide to error handling patterns and troubleshooting common issues.

Overview¶

Understanding errors helps you debug workflows, fix issues quickly, and build robust automation.

Common Error Categories¶

1. Connection Errors¶

Symptoms: - ECONNREFUSED - Connection refused - ETIMEDOUT - Connection timeout - ENOTFOUND - Host not found

Common Causes: - n8n instance not running - Incorrect N8N_HOST URL - Firewall blocking connection - Network issues

Solutions:

# Check n8n is running
curl https://your-n8n-instance.com

# Verify configuration
echo $N8N_HOST

# Test API connectivity
curl -H "X-N8N-API-KEY: your-key" \
  https://your-n8n-instance.com/api/v1/workflows

2. Authentication Errors¶

Symptoms: - 401 Unauthorized - 403 Forbidden

Common Causes: - Invalid API key - Expired API key - Missing API key - Incorrect permissions

Solutions:

1. Regenerate API key in n8n Settings → API
2. Update configuration with new key
3. Restart MCP server
4. Test with: "List workflows"

3. Validation Errors¶

Symptoms: - 400 Bad Request - 422 Unprocessable Entity - Workflow creation fails

Common Causes: - Missing required fields - Invalid parameter formats - Malformed connections - Invalid node types

Solutions: - Check workflow structure - Verify all required nodes - Validate connection format - Review parameter types

4. API Limitations¶

Known Limitations:

Manual Execution:

Issue: execute_workflow() fails for most triggers
Cause: n8n API limitation (v1.82.3)
Solution: Use n8n web interface for manual testing

Credential Retrieval:

Issue: list_credentials() and get_credential() blocked
Cause: Security protection
Solution: Use n8n web UI to view credentials

Tag Updates:

Issue: update_tag() may return 409 Conflict
Cause: API limitation
Solution: Delete + Create pattern

Error Response Format¶

Standard Error Structure¶

{
  error: {
    code: string;          // Error code
    message: string;       // Human-readable message
    details?: any;         // Additional context
  }
}

Common Error Codes¶

Debugging Workflows¶

Enable Debug Mode¶

# Set DEBUG environment variable
DEBUG=true npx @kernel.salacoste/n8n-workflow-builder

Debug Output Includes: - API request details - Response data - Error stack traces - Timing information

Execution Debugging¶

Check Execution Details:

1. Get execution with full data
   → get_execution({ id, includeData: true })

2. Review node outputs
   → Check data flow through workflow

3. Identify failed node
   → Review error message and stack trace

4. Fix and retry
   → retry_execution({ id })

Common Workflow Issues¶

Issue: Workflow Won't Activate

Cause: Missing valid trigger node
Solution: Add scheduleTrigger or webhook node
Tool: activate_workflow() auto-adds trigger if missing

Issue: Execution Fails Immediately

Cause: Missing credentials or invalid configuration
Solution:
1. Check credential assignment in nodes
2. Verify credential exists and is valid
3. Test credentials in n8n UI

Issue: Workflow Runs But No Output

Cause: Nodes disconnected or data not flowing
Solution:
1. Check node connections
2. Verify data mapping
3. Test each node individually

Error Recovery Patterns¶

Automatic Retry Pattern¶

1. Monitor for failures
   → list_executions({ status: 'error' })

2. Analyze error type
   → get_execution({ id, includeData: true })

3. Classify error
   → Temporary (network) vs Permanent (auth)

4. Retry if temporary
   → retry_execution({ id })

5. Alert if permanent
   → Log for manual intervention

Circuit Breaker Pattern¶

1. Track failure rate
   → Count failures in time window

2. If > threshold (e.g., 50% in 5 min)
   → Deactivate workflow temporarily

3. Alert team
   → Notify via Slack/email

4. Manual investigation
   → Fix root cause

5. Reactivate workflow
   → activate_workflow({ id })

Best Practices¶

Error Handling in Workflows¶

Main Flow:
  Try Operation → Success → Continue
                ↓ Error
  Error Handler → Log Error → Alert → Stop

Monitoring¶

Logging¶

Troubleshooting Checklist¶

Connection Issues¶

• n8n instance is running
• N8N_HOST URL is correct (no /api/v1 suffix)
• Network/firewall allows connection
• API endpoint is accessible (curl test)

Authentication Issues¶

• API key is valid and not expired
• API key has correct permissions
• Configuration file is correct
• No whitespace in API key value

Workflow Issues¶

• Workflow has valid trigger node
• All nodes are properly connected
• Credentials are assigned to nodes
• Node parameters are valid

Execution Issues¶

• Workflow is activated
• Trigger conditions are met
• Required services are available
• No rate limiting or quotas exceeded

Getting Help¶

Information to Provide¶

When reporting issues, include:

1. Error Message - Exact error text
2. MCP Server Version - npx @kernel.salacoste/n8n-workflow-builder --version
3. n8n Version - From n8n UI
4. Workflow ID - If workflow-specific
5. Execution ID - If execution-specific
6. Steps to Reproduce - What led to error
7. Debug Logs - With DEBUG=true

Resources¶

• GitHub Issues - Report bugs
• Examples - Common solutions
• API Reference - Technical details

Next Steps¶

• Workflows Management - Create robust workflows
• Executions Management - Monitor and retry
• Examples - Real-world solutions