# 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:**
```bash
# 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
```typescript
{
error: {
code: string; // Error code
message: string; // Human-readable message
details?: any; // Additional context
}
}
```
### Common Error Codes
| Code | Meaning | Action |
|------|---------|--------|
| `401` | Unauthorized | Check API key |
| `404` | Not Found | Verify resource ID |
| `409` | Conflict | Resource already exists or locked |
| `422` | Validation Error | Fix request data |
| `500` | Server Error | Check n8n logs |
| `503` | Service Unavailable | Wait and retry |
---
## Debugging Workflows
### Enable Debug Mode
```bash
# 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
!!! tip "Workflow Design"
**Add Error Handling:**
- Use IF nodes to check for errors
- Add error workflow branches
- Log errors to monitoring system
- Send alerts for critical failures
**Example Pattern:**
```
Main Flow:
Try Operation → Success → Continue
↓ Error
Error Handler → Log Error → Alert → Stop
```
### Monitoring
!!! tip "Proactive Monitoring"
**Daily Checks:**
- Review failed executions
- Check workflow activation status
- Monitor execution duration trends
- Verify credential validity
**Weekly:**
- Clean up old executions
- Review error patterns
- Update workflows based on failures
- Rotate credentials if needed
### Logging
!!! tip "Effective Logging"
**In Workflows:**
- Log before/after critical operations
- Include context (workflow ID, execution ID)
- Log input data (sanitized)
- Log error details
**In MCP Server:**
- Enable DEBUG mode during development
- Log API errors with full context
- Disable verbose logging in production
---
## 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](https://github.com/salacoste/mcp-n8n-workflow-builder/issues) - Report bugs
- [Examples](../troubleshooting/error-reference.md) - Common solutions
- [API Reference](../api/overview.md) - Technical details
---
## Next Steps
- [Workflows Management](workflows-management.md) - Create robust workflows
- [Executions Management](executions-management.md) - Monitor and retry
- [Examples](../troubleshooting/error-reference.md) - Real-world solutions
---
!!! question "Still Having Issues?"
[Report an Issue](https://github.com/salacoste/mcp-n8n-workflow-builder/issues/new)
