# Error Reference Guide

Quick reference for common error messages, their causes, and solutions.

This guide covers errors you might encounter when using the MCP n8n Workflow Builder through Claude Desktop.

---

## Table of Contents

1. [Workflow Errors](#workflow-errors)
2. [Authentication Errors](#authentication-errors)
3. [Connection Errors](#connection-errors)
4. [Execution Errors](#execution-errors)
5. [Integration Errors](#integration-errors)
6. [Configuration Errors](#configuration-errors)
7. [API Errors](#api-errors)

---

## Workflow Errors

### Error: "Workflow validation failed: missing required trigger node"

**Full Message:**
```
Cannot activate workflow without valid trigger node.
Please add scheduleTrigger, webhook, or service-specific trigger before activation.
```

**Cause:**
Attempting to activate a workflow that has no valid trigger node, or only has a `manualTrigger` node.

**Background:**
This is a known limitation from Epic 1. The n8n REST API (v1.82.3) does not recognize `manualTrigger` as a valid trigger for activation.

**Solution via Claude Desktop:**
```
You: "Workflow 123 in staging won't activate. Add a schedule trigger that runs daily at 9 AM."

Claude: I'll add a valid schedule trigger to enable activation.

[MCP tool call: update_workflow]
{
  "instance": "staging",
  "id": "123",
  "nodes": [
    {
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "parameters": {
        "rule": {
          "interval": [{"field": "cronExpression", "expression": "0 9 * * *"}]
        }
      }
    },
    // ... existing nodes
  ]
}

✅ Schedule trigger added
Now you can activate the workflow.
```

**Alternative Solutions:**
1. Add webhook trigger for HTTP-based activation
2. Add service-specific trigger (Slack, GitHub, etc.)
3. Keep manual trigger for n8n UI testing only

**Prevention:**
Always include a valid trigger node when creating workflows intended for automation.

---

### Error: "Invalid workflow definition: connections malformed"

**Symptoms:**
- Workflow creation fails
- Error mentions "connections" or "invalid structure"

**Cause:**
Workflow connections are not in the correct n8n API format.

**Details:**
The MCP server automatically transforms connections between array format (user-friendly) and n8n's object format (API requirement). This error indicates a transformation issue.

**Solution:**
```
You: "I'm getting a connection error when creating a workflow. Here's the structure: [paste workflow JSON]"

Claude: Let me fix the connection format for n8n compatibility.

[Analyzes and corrects connection structure]
[Creates workflow with proper connections]

✅ Workflow created with corrected connections
```

**Technical Note:**
Connections transform from:
```javascript
// Array format (input)
[{source: "node1", target: "node2"}]

// To n8n object format (API)
{"node1": {"main": [[{"node": "node2", "type": "main", "index": 0}]]}}
```

---

## Authentication Errors

### Error: "Authentication failed: Invalid API key"

**HTTP Status:** 401 Unauthorized

**Full Message:**
```
Request failed with status code 401
Authentication failed: Invalid or expired n8n API key
```

**Cause:**
The n8n API key in your configuration is invalid, expired, or revoked.

**Diagnostic Steps:**

```
You: "I'm getting 401 authentication errors for production. Can you test the connection?"

Claude: Let me verify the production instance connection.

[MCP tool call: list_workflows]
{
  "instance": "production",
  "limit": 1
}

Error: Authentication failed (401 Unauthorized)

The production API key appears to be invalid or expired.

**Fix Required:**
1. Open production n8n instance UI
2. Navigate to: Settings → API
3. Regenerate API key
4. Update .config.json with new key:

{
  "environments": {
    "production": {
      "n8n_host": "https://prod.n8n.example.com",
      "n8n_api_key": "NEW_KEY_HERE"
    }
  }
}

5. Restart MCP server
```

**Quick API Key Test:**
```bash
# Test API key manually
curl -X GET 'https://your-n8n.cloud/api/v1/workflows?limit=1' \
  -H 'X-N8N-API-KEY: your_api_key_here'

# Expected responses:
# 200 OK = Valid key ✅
# 401 Unauthorized = Invalid key ❌
```

**Common Causes:**
- API key typo in configuration
- API key regenerated in n8n UI
- API key deleted/revoked
- Wrong instance URL

---

### Error: "Forbidden: Insufficient permissions"

**HTTP Status:** 403 Forbidden

**Cause:**
API key doesn't have required permissions for the operation.

**Solution:**
Check API key permissions in n8n UI:
1. Settings → API
2. Verify key has necessary scopes
3. Regenerate with full permissions if needed

---

## Connection Errors

### Error: "ECONNREFUSED - Connection Refused"

**Full Message:**
```
Error: connect ECONNREFUSED
Failed to connect to n8n instance at [URL]
```

**Cause:**
Cannot establish connection to the n8n instance.

**Common Reasons:**

1. **n8n instance is down**
   ```
   Solution: Verify n8n is running
   - Open n8n URL in browser
   - Check n8n server status
   - Restart n8n if needed
   ```

2. **Wrong URL in configuration**
   ```
   Check .config.json:
   {
     "n8n_host": "https://n8n.example.com"  // Verify this URL
   }

   Common mistakes:
   - Typo in domain name
   - HTTP vs HTTPS
   - Wrong subdomain
   - Including /api/v1/ suffix (remove it!)
   ```

3. **Firewall blocking connection**
   ```
   Test connectivity:
   curl https://your-n8n.cloud/api/v1/workflows

   If this fails, check:
   - Corporate firewall rules
   - Network restrictions
   - VPN requirements
   ```

4. **VPN required but not connected**
   ```
   If n8n is behind VPN:
   - Connect to VPN first
   - Then restart MCP server
   ```

**Diagnostic Conversation:**
```
You: "Getting ECONNREFUSED errors for staging instance"

Claude: Let me help diagnose the connection issue.

**Checks:**
1. Can you access https://staging.n8n.example.com in your browser?
   - Yes → n8n is running, check API key/config
   - No → n8n instance is down or URL is wrong

2. Is the URL in .config.json exactly: https://staging.n8n.example.com
   - No /api/v1/ suffix
   - Correct protocol (http/https)
   - Correct domain

3. Are you on required VPN (if applicable)?

Please check these and let me know what you find.
```

---

### Error: "ETIMEDOUT - Request Timeout"

**Full Message:**
```
Error: timeout of 30000ms exceeded
Request to n8n instance timed out
```

**Cause:**
Request took longer than 30 seconds to complete.

**Common Reasons:**

1. **Slow network connection**
2. **n8n instance overloaded**
3. **Large workflow/execution data**
4. **n8n database performance issues**

**Solutions:**

```
You: "Getting timeout errors when fetching workflow 123"

Claude: Timeouts often occur with large workflows or slow networks.

**Optimized Approach:**
1. First, get workflow metadata (lighter operation)
2. If successful, then fetch full workflow data

[Tries optimized sequence]

Result: Workflow 123 has 150+ nodes which causes timeouts.

**Recommendations:**
- Split into smaller workflows
- Reduce node count
- Check n8n instance performance
- Increase timeout in configuration (if needed)
```

---

### Error: "Invalid URL format: must not include /api/v1/"

**Full Message:**
```
Configuration error: n8n_host must not include /api/v1 suffix
Please use base URL only (e.g., https://n8n.example.com)
The MCP server automatically appends /api/v1 to API calls.
```

**Cause:**
Configuration includes `/api/v1/` in the n8n_host value (Epic 1 common mistake).

**Fix:**

```json
// ❌ Incorrect (will cause errors)
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com/api/v1/",
      "n8n_api_key": "key"
    }
  }
}

// ✅ Correct
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "key"
    }
  }
}
```

**Validation:**
```bash
# Run configuration validator
npm run validate-config

# Should output:
✅ Configuration valid
✅ All n8n_host URLs correctly formatted
```

**After Fix:**
Restart the MCP server to apply configuration changes.

---

## Execution Errors

### Error: "Cannot execute workflow with manual trigger via API"

**Cause:**
n8n REST API limitation (Epic 2 known issue).

**Explanation:**
Workflows with ONLY a `manualTrigger` node cannot be executed via the n8n REST API (v1.82.3). This is a platform limitation, not an MCP server bug.

**MCP Server Response:**
```
You: "Execute workflow 456 in production"

Claude:
[MCP tool call: execute_workflow]
{
  "instance": "production",
  "id": "456"
}

⚠️ Cannot execute via API: Workflow has manual trigger only

This is a known n8n API limitation (v1.82.3).

**Alternative Methods:**

1. **Execute in n8n UI (Recommended)**
   - Open: https://prod.n8n.example.com
   - Navigate to workflow 456
   - Click "Test Workflow"
   - Click "Execute Workflow"

2. **Add Webhook Trigger**
   Would you like me to add a webhook trigger so you can execute via HTTP POST?

3. **Add Schedule Trigger**
   Or add a schedule trigger for automated execution?

Which approach would you prefer?
```

**Solutions:**

**Option 1: Use n8n UI**
```
Navigate to n8n → Open workflow → Test Workflow → Execute
```

**Option 2: Add Webhook**
```
You: "Add a webhook trigger so I can execute it via API"

Claude: I'll add a webhook trigger to enable API execution.

[Adds webhook node]

✅ Webhook trigger added
Execute via: POST https://your-n8n.cloud/webhook/execute-456
```

**Option 3: Add Schedule**
```
You: "Add a schedule trigger that runs every hour"

Claude: [Adds schedule trigger]

✅ Schedule trigger added (runs hourly)
Activate to enable automatic execution.
```

---

### Error: "Execution not found"

**HTTP Status:** 404

**Cause:**
Requesting execution ID that doesn't exist.

**Diagnostic:**
```
You: "Get details for execution 9999 in production"

Claude:
[MCP tool call: get_execution]
{
  "instance": "production",
  "id": "9999"
}

Error: Execution 9999 not found in production

Possible reasons:
1. Wrong execution ID
2. Execution from different instance
3. Execution deleted/purged

**Find recent executions:**
Would you like me to list recent executions for:
- Specific workflow?
- All executions from today?
- Failed executions only?
```

---

## Integration Errors

### Slack: "channel_not_found"

**Error in Execution:**
```
Slack API Error: channel_not_found
The channel does not exist or the bot is not a member
```

**Cause:**
Slack bot not invited to the target channel.

**Solution:**
```
1. Open Slack
2. Navigate to the channel
3. Type: /invite @YourBotName
4. Retry workflow execution
```

**Alternative (for public channels):**
Use `chat:write.public` permission to post without invitation.

**Bot Permission Setup:**
```
Slack App → OAuth & Permissions → Scopes:
- chat:write (required)
- chat:write.public (posts to public channels without invite)
```

---

### Gmail: "The caller does not have permission"

**Cause:**
Gmail API not enabled or OAuth scope insufficient.

**Fix:**
```
1. Google Cloud Console
2. APIs & Services → Enable APIs
3. Search "Gmail API"
4. Click "Enable"
5. Re-authenticate n8n credential
```

**OAuth Scopes Required:**
```
- https://www.googleapis.com/auth/gmail.send
- https://www.googleapis.com/auth/gmail.compose
```

---

### Google Sheets: "The caller does not have permission"

**Cause:**
Google Sheet not shared with OAuth email.

**Solution:**
```
1. Open Google Sheet
2. Click "Share" (top right)
3. Add OAuth email address from n8n credential
4. Grant "Editor" permission
5. Click "Send"
6. Retry workflow
```

**Find OAuth Email:**
```
n8n UI → Settings → Credentials → [Your Google Sheets Credential] → View Details
```

---

### SMTP: "Authentication failed"

**For Gmail:**
**Cause:** Using account password instead of App Password

**Solution:**
```
1. Google Account → Security
2. Enable 2-Step Verification (if not enabled)
3. Click "App passwords"
4. Select: Mail → Other (Custom name: "n8n")
5. Generate
6. Copy 16-character password
7. Update n8n SMTP credential with App Password
```

**For Outlook/Office 365:**
**Cause:** Less secure app access disabled

**Solution:**
```
1. Microsoft Account → Security
2. Advanced security options
3. Enable "App passwords"
4. Generate app-specific password
5. Use in n8n
```

---

## Configuration Errors

### Error: "Instance 'production' not found"

**Full Message:**
```
Instance "production" not found in configuration.

Available instances: staging, development

Please use one of the available instance names or add 'production' to .config.json
```

**Cause:**
Requesting an instance that doesn't exist in `.config.json`.

**Solution:**

**Check Configuration:**
```
You: "What instances are configured in my setup?"

Claude: Let me check your configuration.

[Reads .config.json]

**Configured Instances:**
1. staging (default)
   - URL: https://staging.n8n.example.com

2. development
   - URL: http://localhost:5678

The 'production' instance is not configured.

**To add production:**
Update .config.json:

{
  "environments": {
    "production": {
      "n8n_host": "https://prod.n8n.example.com",
      "n8n_api_key": "your_production_api_key"
    },
    "staging": {...},
    "development": {...}
  },
  "defaultEnv": "staging"
}

After updating, restart the MCP server.
```

---

### Error: "Configuration file not found"

**Cause:**
No `.config.json` or `.env` file found.

**Solution:**
```bash
# Option 1: Create .config.json (multi-instance)
cat > .config.json << 'EOF'
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "your_api_key"
    }
  },
  "defaultEnv": "production"
}
EOF

# Option 2: Create .env (single instance)
cat > .env << 'EOF'
N8N_HOST=https://n8n.example.com
N8N_API_KEY=your_api_key
EOF

# Validate configuration
npm run validate-config
```

---

## API Errors

### Error 422: "Unprocessable Entity"

**Cause:**
Request data doesn't meet n8n API validation requirements.

**Common Issues:**
- Missing required fields
- Invalid data types
- Malformed JSON
- Invalid node parameters

**Solution:**
```
You: "Getting 422 error when creating workflow"

Claude: 422 errors indicate validation issues. Let me check the workflow definition.

[Analyzes workflow structure]

**Issues Found:**
1. Missing required parameter in HTTP Request node
2. Invalid cron expression in Schedule Trigger
3. Empty node connections

**Fixed Issues:**
[Creates corrected workflow]

✅ Workflow created successfully
All validation issues resolved.
```

---

### Error 409: "Conflict"

**Common With:** Tag updates

**Cause:**
Tag name already exists or conflicts with existing tag.

**Workaround:**
```
You: "Update tag 5 to rename it to 'customer-workflows'"

Claude:
[MCP tool call: update_tag]

Error: 409 Conflict - Tag name may already exist

**Workaround (Epic 2 known issue):**
1. Delete old tag
2. Create new tag with desired name

Would you like me to:
1. Delete tag 5
2. Create new tag "customer-workflows"
3. Re-tag affected workflows
```

---

## Quick Diagnostic Checklist

### Workflow Won't Activate
- [ ] Has valid trigger node? (not manualTrigger)
- [ ] Workflow definition valid JSON?
- [ ] No syntax errors in expressions?
- [ ] All required credentials configured?
- [ ] Instance name correct?

### Workflow Won't Execute
- [ ] Workflow activated?
- [ ] Has manual trigger? (API limitation - use n8n UI)
- [ ] Trigger configuration correct?
- [ ] Tested in n8n UI?

### API Connection Issues
- [ ] n8n instance running?
- [ ] API key valid and not expired?
- [ ] URL correct (no /api/v1/ suffix)?
- [ ] Network/firewall allowing connection?
- [ ] VPN connected (if required)?

### Integration Not Working
- [ ] Credentials configured in n8n UI?
- [ ] Service-specific permissions granted?
- [ ] API rate limits not exceeded?
- [ ] Service account has required access?
- [ ] Correct credential ID referenced?

---

## Getting Additional Help

### 1. Enable Debug Logging
```bash
# Check MCP server logs
npm start 2> mcp-server.log
tail -f mcp-server.log
```

### 2. Validate Configuration
```bash
npm run validate-config
```

### 3. Test API Directly
```bash
curl -X GET 'https://your-n8n.cloud/api/v1/workflows?limit=1' \
  -H 'X-N8N-API-KEY: your_api_key' \
  -v
```

### 4. Check n8n Logs
```
n8n UI → Executions → Click execution → View Details
```

### 5. Report Issues
GitHub Issues: https://github.com/your-org/mcp-n8n-workflow-builder/issues

**Include:**
- Error message (redact API keys!)
- MCP server version: `npm list @kernel.salacoste/n8n-workflow-builder`
- n8n version
- Steps to reproduce
- Relevant configuration (redact sensitive data)

---

## Related Documentation

- [FAQ](./faq.md) - Frequently Asked Questions
- [Debug Mode Guide](./debug-mode.md) - Logging and debugging workflows
- [Claude Desktop Patterns](../guides/claude-desktop-patterns.md) - Effective usage
- [Multi-Instance Configuration](../multi-instance/configuration.md) - Setup guide

---

**Last Updated:** January 2025
**Version:** 1.0
**Feedback:** Report errors or suggest additions via GitHub issues