Error Reference Guide¶

Cannot activate workflow without valid trigger node.
Please add scheduleTrigger, webhook, or service-specific trigger before activation.

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.

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

Request failed with status code 401
Authentication failed: Invalid or expired n8n API key

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

Error: connect ECONNREFUSED
Failed to connect to n8n instance at [URL]

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: timeout of 30000ms exceeded
Request to n8n instance timed out

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)

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.

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?

Navigate to n8n → Open workflow → Test Workflow → Execute

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

You: "Add a schedule trigger that runs every hour"

Claude: [Adds schedule trigger]

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

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?

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

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

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

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

- https://www.googleapis.com/auth/gmail.send
- https://www.googleapis.com/auth/gmail.compose

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

n8n UI → Settings → Credentials → [Your Google Sheets Credential] → View Details

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

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

Instance "production" not found in configuration.

Available instances: staging, development

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

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.

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.

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

n8n UI → Executions → Click execution → View Details