# Story 4.6: Error Handling & Common Patterns Reference
**Epic:** Epic 4 - Core Features & Tools Reference Documentation
**Story Points:** 7
**Priority:** High
**Status:** Ready for Implementation
**Estimated Page Count:** 12-15 pages
---
## User Story
**As a** developer integrating the n8n MCP server into applications
**I want** comprehensive error handling documentation and common patterns reference
**So that** I can build robust integrations, troubleshoot issues efficiently, and follow best practices
---
## Story Description
### Current System
The n8n MCP server currently provides:
- **17 MCP Tools** with various error scenarios
- **4 MCP Resources** with potential failure modes
- **Multi-instance architecture** with routing complexities
- **n8n REST API integration** with HTTP error responses
However, error handling patterns are scattered across tool documentation:
- No centralized error reference
- Missing troubleshooting decision trees
- Undocumented common mistakes
- No validation pattern library
- Limited retry strategies
### Enhancement
Create comprehensive error handling and patterns documentation that:
- Catalogs all possible error types with resolutions
- Provides troubleshooting decision trees for common scenarios
- Documents validation patterns for data integrity
- Establishes best practices for robust integrations
- Includes error recovery strategies
- Cross-references errors with affected tools
### Context from Previous Epics
**Epic 1 (URL Configuration):**
- URL validation errors and normalization failures
- /api/v1/ suffix handling errors
**Epic 2 (API Implementation):**
- Credential API security restrictions (LIST/GET blocked)
- Tag update 409 Conflict issue
- Manual trigger execution limitation
**Epic 5 (Multi-Instance):**
- Instance not found errors
- Default environment fallback
- Instance validation failures
---
## Acceptance Criteria
### AC1: Error Type Catalog
**Given** a developer encountering an error
**When** they consult the error catalog
**Then** they should find:
#### 1.1 Configuration Errors
**Error Type:** Missing Configuration
```typescript
{
code: "CONFIGURATION_ERROR",
message: "No configuration found. Please create .config.json or .env file",
category: "Configuration",
severity: "Critical",
resolution: "Create configuration file with n8n_host and n8n_api_key"
}
```
**Affected Tools:** All tools (server startup)
**Common Causes:**
- Missing .config.json and .env files
- Empty configuration files
- Invalid JSON syntax in .config.json
**Resolution Steps:**
```bash
# Option 1: Create .env file
echo "N8N_HOST=https://your-instance.app.n8n.cloud" > .env
echo "N8N_API_KEY=your_api_key_here" >> .env
# Option 2: Create .config.json file
cat > .config.json << EOF
{
"environments": {
"production": {
"n8n_host": "https://your-instance.app.n8n.cloud",
"n8n_api_key": "your_api_key_here"
}
},
"defaultEnv": "production"
}
EOF
```
**Claude Desktop Example:**
```
Error: "Failed to initialize MCP server: No configuration found"
Resolution:
1. Check configuration file exists
2. Verify JSON syntax (if using .config.json)
3. Ensure required fields present (n8n_host, n8n_api_key)
4. Restart MCP server after fixing
```
---
**Error Type:** Invalid URL Format (Epic 1)
```typescript
{
code: "INVALID_URL",
message: "n8n_host must be a valid URL without /api/v1/ suffix",
category: "Configuration",
severity: "High",
resolution: "Use base URL only (e.g., https://n8n.example.com)"
}
```
**Affected Tools:** All tools
**Common Mistakes:**
```typescript
// ❌ Incorrect - includes /api/v1/
"n8n_host": "https://n8n.example.com/api/v1/"
// ❌ Incorrect - missing protocol
"n8n_host": "n8n.example.com"
// ❌ Incorrect - has trailing path
"n8n_host": "https://n8n.example.com/workflows"
// ✅ Correct - base URL only
"n8n_host": "https://n8n.example.com"
```
**Resolution Pattern:**
```typescript
// URL validation function (from Epic 1)
function validateAndNormalizeUrl(url: string): string {
if (url.endsWith('/api/v1/') || url.endsWith('/api/v1')) {
throw new Error('Remove /api/v1/ from n8n_host - use base URL only');
}
if (!url.startsWith('http://') && !url.startsWith('https://')) {
throw new Error('n8n_host must include protocol (https://)');
}
return url.replace(/\/$/, ''); // Remove trailing slash
}
```
---
**Error Type:** Invalid API Key
```typescript
{
code: "AUTHENTICATION_ERROR",
message: "Invalid API key or insufficient permissions",
httpStatus: 401,
category: "Authentication",
severity: "Critical"
}
```
**Affected Tools:** All tools
**Common Causes:**
- Incorrect API key
- Expired API key
- Insufficient n8n user permissions
- API key for wrong n8n instance
**Resolution Steps:**
1. Verify API key in n8n UI (Settings → API)
2. Check user has necessary permissions
3. Ensure API key matches n8n instance
4. Regenerate API key if needed
**Troubleshooting Decision Tree:**
```
Authentication Error
├─ API key wrong instance?
│ └─ Update to correct instance API key
├─ API key expired?
│ └─ Regenerate in n8n UI
├─ User permissions insufficient?
│ └─ Grant necessary permissions in n8n
└─ API key typo?
└─ Copy-paste from n8n UI (no manual typing)
```
---
#### 1.2 Multi-Instance Errors (Epic 5)
**Error Type:** Instance Not Found
```typescript
{
code: "INSTANCE_NOT_FOUND",
message: "Instance 'staging' not found. Available: production, development",
category: "Multi-Instance",
severity: "High",
availableInstances: ["production", "development"]
}
```
**Affected Tools:** All tools with `instance` parameter
**Common Causes:**
- Typo in instance name
- Instance not configured in .config.json
- Using instance name when only .env configured
**Resolution Pattern:**
```typescript
// Always validate instance before API call
async function validateInstance(instance?: string): Promise<string> {
const envManager = EnvironmentManager.getInstance();
const available = envManager.listEnvironments();
if (instance && !available.includes(instance)) {
throw new Error(
`Instance '${instance}' not found. Available: ${available.join(', ')}`
);
}
return instance || envManager.getDefaultEnvironment();
}
```
**Claude Desktop Example:**
```
User: "List workflows from staging instance"
Error: "Instance 'staging' not found. Available: production, development"
Resolution:
1. Check .config.json for configured instances
2. Verify instance name spelling
3. Add missing instance to configuration if needed
4. Use correct instance name in tool call
```
---
**Error Type:** Default Environment Not Set
```typescript
{
code: "DEFAULT_ENV_MISSING",
message: "No defaultEnv specified and no instance provided",
category: "Multi-Instance",
severity: "Medium"
}
```
**Resolution:**
```json
{
"environments": { ... },
"defaultEnv": "production" // ← Add this
}
```
---
#### 1.3 Workflow Operation Errors
**Error Type:** Workflow Not Found
```typescript
{
code: "WORKFLOW_NOT_FOUND",
message: "Workflow with ID '123' not found",
httpStatus: 404,
category: "Workflow",
severity: "Medium"
}
```
**Affected Tools:** get_workflow, update_workflow, delete_workflow, activate_workflow, deactivate_workflow, execute_workflow
**Common Causes:**
- Incorrect workflow ID
- Workflow deleted
- Wrong instance selected
**Resolution Pattern:**
```typescript
// Always list workflows first to verify ID
const workflows = await listWorkflows({ instance: 'production' });
const workflow = workflows.data.find(w => w.name === 'My Workflow');
if (!workflow) {
throw new Error('Workflow not found - verify name and instance');
}
// Now use verified ID
await getWorkflow({ id: workflow.id, instance: 'production' });
```
---
**Error Type:** Invalid Workflow Structure
```typescript
{
code: "VALIDATION_ERROR",
message: "Workflow validation failed: missing required trigger node",
category: "Workflow",
severity: "High",
details: {
field: "nodes",
issue: "No valid trigger node found"
}
}
```
**Affected Tools:** create_workflow, update_workflow, activate_workflow
**Common Causes:**
- Missing trigger nodes
- Invalid node type
- Malformed connections
- Invalid Set node parameters (Epic 2)
**Validation Pattern:**
```typescript
// Workflow validation checklist
function validateWorkflow(workflow: WorkflowDefinition): void {
// 1. Check required fields
if (!workflow.name) throw new Error('Workflow name required');
if (!workflow.nodes || workflow.nodes.length === 0) {
throw new Error('Workflow must have at least one node');
}
// 2. Validate trigger for activation
const hasTrigger = workflow.nodes.some(node =>
node.type.includes('Trigger') || node.type.includes('webhook')
);
if (workflow.active && !hasTrigger) {
throw new Error('Active workflows require valid trigger node');
}
// 3. Validate connections format
if (workflow.connections) {
// Check if using array format (needs transformation)
if (Array.isArray(workflow.connections)) {
workflow.connections = transformConnectionsForN8N(workflow.connections);
}
}
// 4. Validate Set node parameters (Epic 2)
workflow.nodes.forEach(node => {
if (node.type === 'n8n-nodes-base.set') {
node.parameters = normalizeSetNodeParameters(node.parameters);
}
});
}
```
---
**Error Type:** Activation Without Valid Trigger (Epic 1)
```typescript
{
code: "ACTIVATION_ERROR",
message: "Cannot activate workflow without valid trigger node",
category: "Workflow",
severity: "High",
resolution: "Add scheduleTrigger or webhook node before activation"
}
```
**Affected Tools:** activate_workflow, create_workflow (with active: true)
**Known Issue from Epic 1:**
- `manualTrigger` NOT recognized as valid by n8n API v1.82.3
- Server automatically adds scheduleTrigger if missing
**Resolution Pattern:**
```typescript
// Auto-add trigger before activation
async function ensureValidTrigger(workflow: WorkflowDefinition): Promise<void> {
const hasTrigger = workflow.nodes.some(node =>
node.type === 'n8n-nodes-base.scheduleTrigger' ||
node.type === 'n8n-nodes-base.webhook' ||
node.type.toLowerCase().includes('trigger')
);
if (!hasTrigger) {
console.warn('No valid trigger found, adding scheduleTrigger');
workflow.nodes.push({
name: 'Schedule Trigger',
type: 'n8n-nodes-base.scheduleTrigger',
typeVersion: 1,
position: [250, 300],
parameters: {
rule: { interval: [{ field: 'hours', hoursInterval: 1 }] }
}
});
}
}
```
---
**Error Type:** Manual Trigger Execution Limitation (Epic 2)
```typescript
{
code: "EXECUTION_NOT_SUPPORTED",
message: "Workflows with only manual triggers cannot be executed via REST API",
category: "Workflow",
severity: "Medium",
workaround: "Execute manually in n8n UI or add valid trigger node"
}
```
**Affected Tools:** execute_workflow
**Known API Limitation:** n8n REST API v1.82.3 cannot execute manual-trigger workflows
**Workaround:**
```typescript
async function executeWorkflow(params: { id: string }): Promise<string> {
// Server returns helpful guidance instead of failing
return `
Workflow execution via REST API is only supported for workflows with:
- scheduleTrigger nodes
- webhook nodes
- service-specific triggers
For manual-trigger workflows:
1. Open n8n UI
2. Navigate to workflow
3. Click "Test Workflow" button
Alternatively:
- Add a valid trigger node (schedule or webhook)
- Use activate_workflow to enable automatic execution
`.trim();
}
```
---
#### 1.4 Execution Operation Errors
**Error Type:** Execution Not Found
```typescript
{
code: "EXECUTION_NOT_FOUND",
message: "Execution with ID '9999' not found",
httpStatus: 404,
category: "Execution",
severity: "Low"
}
```
**Affected Tools:** get_execution, delete_execution, retry_execution
**Common Causes:**
- Incorrect execution ID
- Execution deleted
- Execution from different instance
**Resolution:**
```typescript
// List executions first to find ID
const executions = await listExecutions({
workflowId: '123',
limit: 10,
instance: 'production'
});
const failedExecution = executions.data.find(e => !e.finished);
if (failedExecution) {
await retryExecution({ id: failedExecution.id, instance: 'production' });
}
```
---
**Error Type:** Retry Already Successful
```typescript
{
code: "RETRY_NOT_NEEDED",
message: "Execution completed successfully - retry not needed",
category: "Execution",
severity: "Low"
}
```
**Affected Tools:** retry_execution
**Common Cause:** Attempting to retry successful execution
**Resolution Pattern:**
```typescript
// Check execution status before retry
async function safeRetry(executionId: number, instance?: string): Promise<void> {
const execution = await getExecution({ id: executionId, instance });
if (execution.finished && !execution.data?.resultData?.error) {
throw new Error(
`Execution ${executionId} completed successfully - retry not needed`
);
}
if (!execution.finished) {
throw new Error(
`Execution ${executionId} still running - wait for completion before retry`
);
}
// Safe to retry
await retryExecution({ id: executionId, instance });
}
```
---
#### 1.5 Credential Operation Errors (Epic 2)
**Error Type:** Credential List/Get Blocked by n8n
```typescript
{
code: "CREDENTIAL_ACCESS_BLOCKED",
message: "n8n blocks LIST and GET operations for credential security",
category: "Credential",
severity: "Info",
workaround: "Use n8n UI or schema-driven creation pattern"
}
```
**Affected Tools:** list_credentials, get_credential
**Known Security Restriction:** n8n API intentionally blocks these operations
**Resolution Pattern:**
```typescript
// Use schema-driven creation instead of GET
async function createCredentialSafely(type: string, data: any): Promise<void> {
// Step 1: Get schema to understand required fields
const schema = await getCredentialSchema({ type });
// Step 2: Validate data against schema
const requiredFields = schema.properties
.filter(p => p.required)
.map(p => p.name);
const missingFields = requiredFields.filter(field => !data[field]);
if (missingFields.length > 0) {
throw new Error(
`Missing required fields: ${missingFields.join(', ')}`
);
}
// Step 3: Create with validated data
await createCredential({
name: 'My Credential',
type,
data
});
}
```
---
**Error Type:** Credential Update Not Supported
```typescript
{
code: "CREDENTIAL_IMMUTABLE",
message: "Credentials cannot be updated - use DELETE + CREATE pattern",
category: "Credential",
severity: "Info"
}
```
**Affected Tools:** update_credential
**Known Limitation:** Credential immutability for security
**UPDATE Pattern:**
```typescript
// DELETE + CREATE pattern for credential updates
async function updateCredentialPattern(
credentialId: string,
newData: CredentialData,
instance?: string
): Promise<void> {
// Step 1: Delete old credential
await deleteCredential({ id: credentialId, instance });
// Step 2: Create new credential with updated data
const newCredential = await createCredential({
name: newData.name,
type: newData.type,
data: newData.data,
instance
});
console.log(`Credential updated: ${credentialId} → ${newCredential.id}`);
}
```
---
#### 1.6 Tag Operation Errors (Epic 2)
**Error Type:** Tag Update 409 Conflict
```typescript
{
code: "TAG_UPDATE_CONFLICT",
message: "Tag update returned 409 Conflict",
httpStatus: 409,
category: "Tag",
severity: "Medium",
knownIssue: "Updating existing tag names may cause conflicts"
}
```
**Affected Tools:** update_tag
**Known Issue from Epic 2:** Tag name updates sometimes return 409 Conflict
**Workaround:**
```typescript
// Use unique names to avoid conflicts
function generateUniqueTagName(baseName: string): string {
const timestamp = Date.now();
return `${baseName}-${timestamp}`;
}
// Or use DELETE + CREATE pattern
async function updateTagSafely(
tagId: string,
newName: string,
instance?: string
): Promise<void> {
try {
await updateTag({ id: tagId, name: newName, instance });
} catch (error) {
if (error.response?.status === 409) {
console.warn('Tag update conflict, using DELETE + CREATE pattern');
await deleteTag({ id: tagId, instance });
await createTag({ name: newName, instance });
} else {
throw error;
}
}
}
```
---
#### 1.7 Connection & Network Errors
**Error Type:** Connection Timeout
```typescript
{
code: "NETWORK_TIMEOUT",
message: "Request to n8n API timed out after 30000ms",
category: "Network",
severity: "High"
}
```
**Affected Tools:** All tools
**Common Causes:**
- n8n instance down
- Network connectivity issues
- Firewall blocking requests
- Large workflow/execution data
**Resolution Pattern:**
```typescript
// Retry with exponential backoff
async function retryWithBackoff<T>(
operation: () => Promise<T>,
maxRetries = 3
): Promise<T> {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (error) {
if (attempt === maxRetries) throw error;
const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
console.warn(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw new Error('Max retries exceeded');
}
// Usage
const workflow = await retryWithBackoff(() =>
getWorkflow({ id: '123', instance: 'production' })
);
```
---
**Error Type:** Rate Limiting
```typescript
{
code: "RATE_LIMIT_EXCEEDED",
message: "Too many requests - rate limit exceeded",
httpStatus: 429,
category: "Network",
severity: "Medium",
retryAfter: 60
}
```
**Resolution Pattern:**
```typescript
// Implement rate limiting
class RateLimiter {
private lastRequest = 0;
private minInterval = 100; // 100ms between requests
async throttle(): Promise<void> {
const now = Date.now();
const elapsed = now - this.lastRequest;
if (elapsed < this.minInterval) {
await new Promise(resolve =>
setTimeout(resolve, this.minInterval - elapsed)
);
}
this.lastRequest = Date.now();
}
}
// Usage
const limiter = new RateLimiter();
for (const workflow of workflows) {
await limiter.throttle();
await updateWorkflow({ id: workflow.id, active: true });
}
```
---
### AC2: Troubleshooting Decision Trees
**Given** a developer encountering a specific scenario
**When** they follow the decision tree
**Then** they should reach a resolution:
#### 2.1 Workflow Creation Troubleshooting
```
Workflow Creation Failed
├─ "Workflow validation failed"?
│ ├─ Missing trigger node?
│ │ └─ Add scheduleTrigger or webhook node
│ ├─ Invalid node type?
│ │ └─ Verify node type exists in n8n instance
│ ├─ Malformed connections?
│ │ └─ Use transformConnectionsForN8N() utility
│ └─ Invalid Set node parameters?
│ └─ Use normalizeSetNodeParameters() (Epic 2)
│
├─ "Invalid URL"?
│ ├─ Contains /api/v1/?
│ │ └─ Remove suffix, use base URL only (Epic 1)
│ ├─ Missing protocol?
│ │ └─ Add https:// prefix
│ └─ Has trailing path?
│ └─ Use base domain only
│
├─ "Authentication error"?
│ ├─ API key incorrect?
│ │ └─ Copy from n8n UI Settings → API
│ ├─ Wrong instance?
│ │ └─ Verify n8n_host matches API key instance
│ └─ Insufficient permissions?
│ └─ Grant user necessary permissions in n8n
│
└─ "Instance not found"?
├─ Typo in instance name?
│ └─ Check .config.json for exact names
├─ Instance not configured?
│ └─ Add to .config.json environments
└─ Using .env instead of .config.json?
└─ Convert to multi-instance config (Epic 5)
```
---
#### 2.2 Workflow Activation Troubleshooting
```
Workflow Activation Failed
├─ "No valid trigger node"?
│ ├─ Has manualTrigger?
│ │ └─ Replace with scheduleTrigger (manualTrigger not valid)
│ ├─ No trigger at all?
│ │ └─ Add scheduleTrigger or webhook node
│ └─ Custom trigger not recognized?
│ └─ Verify trigger node type exists in n8n
│
├─ "Workflow not found"?
│ ├─ Incorrect ID?
│ │ └─ Use list_workflows to verify ID
│ ├─ Wrong instance?
│ │ └─ Check instance parameter matches workflow location
│ └─ Workflow deleted?
│ └─ Recreate workflow
│
└─ "Authentication error"?
└─ (See Workflow Creation troubleshooting)
```
---
#### 2.3 Execution Troubleshooting
```
Execution Failed
├─ "Cannot execute workflow"?
│ ├─ Manual trigger only?
│ │ └─ Execute in n8n UI or add valid trigger (Epic 2 limitation)
│ ├─ Workflow inactive?
│ │ └─ Activate workflow first
│ └─ Missing credentials?
│ └─ Configure credentials in n8n UI
│
├─ "Execution not found"?
│ ├─ Incorrect execution ID?
│ │ └─ Use list_executions to find ID
│ ├─ Wrong instance?
│ │ └─ Verify instance parameter
│ └─ Execution deleted?
│ └─ Cannot retrieve deleted executions
│
└─ Retry failed?
├─ Execution successful?
│ └─ No need to retry successful executions
├─ Execution still running?
│ └─ Wait for completion before retry
└─ Same error on retry?
└─ Fix workflow issue before retrying again
```
---
#### 2.4 Credential Troubleshooting
```
Credential Operation Failed
├─ "Cannot list credentials"?
│ └─ n8n blocks for security (Epic 2)
│ └─ Use n8n UI or schema-driven creation
│
├─ "Cannot get credential"?
│ └─ n8n blocks for security (Epic 2)
│ └─ Use get_credential_schema for field info
│
├─ "Cannot update credential"?
│ └─ Credentials are immutable
│ └─ Use DELETE + CREATE pattern
│
├─ "Invalid credential type"?
│ └─ Check available credential types in n8n UI
│
└─ "Missing required fields"?
├─ Use get_credential_schema first
│ └─ See required fields and their types
└─ Validate data against schema before creation
```
---
### AC3: Validation Patterns Library
**Given** a developer implementing robust integrations
**When** they use validation patterns
**Then** they should prevent common errors:
#### 3.1 Input Validation Pattern
```typescript
/**
* Validates and normalizes tool input parameters
*/
class InputValidator {
/**
* Validate workflow ID
*/
static validateWorkflowId(id: any): string {
if (!id) throw new Error('Workflow ID required');
if (typeof id !== 'string' && typeof id !== 'number') {
throw new Error('Workflow ID must be string or number');
}
return String(id);
}
/**
* Validate instance name
*/
static validateInstance(instance: any, availableInstances: string[]): string | undefined {
if (!instance) return undefined;
if (typeof instance !== 'string') {
throw new Error('Instance must be a string');
}
if (!availableInstances.includes(instance)) {
throw new Error(
`Instance '${instance}' not found. Available: ${availableInstances.join(', ')}`
);
}
return instance;
}
/**
* Validate pagination parameters
*/
static validatePagination(params: {
limit?: any;
cursor?: any;
}): { limit?: number; cursor?: string } {
const result: { limit?: number; cursor?: string } = {};
if (params.limit !== undefined) {
const limit = Number(params.limit);
if (isNaN(limit) || limit < 1 || limit > 250) {
throw new Error('Limit must be between 1 and 250');
}
result.limit = limit;
}
if (params.cursor !== undefined) {
if (typeof params.cursor !== 'string') {
throw new Error('Cursor must be a string');
}
result.cursor = params.cursor;
}
return result;
}
/**
* Validate workflow definition
*/
static validateWorkflowDefinition(workflow: any): void {
if (!workflow.name || typeof workflow.name !== 'string') {
throw new Error('Workflow name required (string)');
}
if (!Array.isArray(workflow.nodes)) {
throw new Error('Workflow nodes must be an array');
}
if (workflow.nodes.length === 0) {
throw new Error('Workflow must have at least one node');
}
// Validate each node
workflow.nodes.forEach((node: any, index: number) => {
if (!node.name) {
throw new Error(`Node ${index} missing name`);
}
if (!node.type) {
throw new Error(`Node ${index} (${node.name}) missing type`);
}
if (!node.position || !Array.isArray(node.position)) {
throw new Error(`Node ${index} (${node.name}) missing position array`);
}
});
}
}
```
---
#### 3.2 Error Handling Pattern
```typescript
/**
* Standardized error handling for n8n API calls
*/
class ErrorHandler {
/**
* Handle API errors with context
*/
static handleApiError(context: string, error: unknown): never {
if (axios.isAxiosError(error)) {
const status = error.response?.status;
const data = error.response?.data;
// Authentication errors
if (status === 401) {
throw new Error(
`Authentication failed for ${context}: Invalid API key or insufficient permissions`
);
}
// Not found errors
if (status === 404) {
throw new Error(
`Resource not found for ${context}: ${data?.message || 'Entity does not exist'}`
);
}
// Validation errors
if (status === 400) {
throw new Error(
`Validation failed for ${context}: ${data?.message || 'Invalid request parameters'}`
);
}
// Conflict errors (e.g., tag updates)
if (status === 409) {
throw new Error(
`Conflict for ${context}: ${data?.message || 'Resource conflict - try DELETE + CREATE pattern'}`
);
}
// Rate limiting
if (status === 429) {
const retryAfter = error.response?.headers['retry-after'] || 60;
throw new Error(
`Rate limit exceeded for ${context}: Retry after ${retryAfter} seconds`
);
}
// Server errors
if (status && status >= 500) {
throw new Error(
`n8n server error for ${context}: ${data?.message || 'Internal server error'}`
);
}
// Generic HTTP error
throw new Error(
`HTTP error ${status} for ${context}: ${data?.message || error.message}`
);
}
// Network errors
if (error instanceof Error && error.message.includes('ECONNREFUSED')) {
throw new Error(
`Cannot connect to n8n instance for ${context}: Check n8n_host configuration`
);
}
if (error instanceof Error && error.message.includes('timeout')) {
throw new Error(
`Request timeout for ${context}: n8n instance may be slow or down`
);
}
// Generic errors
throw new Error(
`Unexpected error for ${context}: ${error instanceof Error ? error.message : String(error)}`
);
}
/**
* Safe async wrapper with error context
*/
static async withContext<T>(
context: string,
operation: () => Promise<T>
): Promise<T> {
try {
return await operation();
} catch (error) {
this.handleApiError(context, error);
}
}
}
// Usage example
const workflow = await ErrorHandler.withContext(
'get workflow 123',
() => api.getWorkflow('123')
);
```
---
#### 3.3 Retry Pattern
```typescript
/**
* Retry logic with exponential backoff
*/
class RetryHandler {
static async withRetry<T>(
operation: () => Promise<T>,
options: {
maxRetries?: number;
baseDelay?: number;
maxDelay?: number;
retryableErrors?: number[];
} = {}
): Promise<T> {
const {
maxRetries = 3,
baseDelay = 1000,
maxDelay = 30000,
retryableErrors = [408, 429, 500, 502, 503, 504]
} = options;
let lastError: Error | undefined;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (error) {
lastError = error instanceof Error ? error : new Error(String(error));
// Check if error is retryable
const isRetryable =
axios.isAxiosError(error) &&
error.response?.status &&
retryableErrors.includes(error.response.status);
if (!isRetryable || attempt === maxRetries) {
throw lastError;
}
// Calculate delay with exponential backoff
const delay = Math.min(
baseDelay * Math.pow(2, attempt - 1),
maxDelay
);
console.warn(
`Attempt ${attempt}/${maxRetries} failed, retrying in ${delay}ms...`
);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw lastError || new Error('Retry failed');
}
}
// Usage example
const workflow = await RetryHandler.withRetry(
() => api.getWorkflow('123'),
{
maxRetries: 3,
baseDelay: 1000,
retryableErrors: [429, 500, 502, 503]
}
);
```
---
#### 3.4 Safe Workflow Modification Pattern
```typescript
/**
* Safe workflow modification with validation
*/
class WorkflowModifier {
/**
* Safely update workflow with rollback capability
*/
static async safeUpdate(params: {
workflowId: string;
updates: Partial<WorkflowDefinition>;
instance?: string;
validateBeforeUpdate?: boolean;
}): Promise<WorkflowDefinition> {
const { workflowId, updates, instance, validateBeforeUpdate = true } = params;
// Step 1: Get current workflow (backup)
const currentWorkflow = await api.getWorkflow(workflowId, instance);
try {
// Step 2: Merge updates
const updatedWorkflow = {
...currentWorkflow,
...updates
};
// Step 3: Validate if requested
if (validateBeforeUpdate) {
InputValidator.validateWorkflowDefinition(updatedWorkflow);
// Transform connections if needed
if (updatedWorkflow.connections && Array.isArray(updatedWorkflow.connections)) {
updatedWorkflow.connections = transformConnectionsForN8N(
updatedWorkflow.connections
);
}
// Normalize Set nodes if needed
updatedWorkflow.nodes = updatedWorkflow.nodes.map(node => {
if (node.type === 'n8n-nodes-base.set') {
return {
...node,
parameters: normalizeSetNodeParameters(node.parameters)
};
}
return node;
});
}
// Step 4: Apply update
return await api.updateWorkflow(workflowId, updatedWorkflow, instance);
} catch (error) {
console.error('Workflow update failed, current state preserved');
throw error; // Original workflow still intact in n8n
}
}
}
```
---
### AC4: Best Practices Guide
**Given** a developer building production integrations
**When** they follow best practices
**Then** they should create robust, maintainable code:
#### 4.1 Configuration Best Practices
**✅ DO:**
```typescript
// Use multi-instance configuration
{
"environments": {
"production": { "n8n_host": "...", "n8n_api_key": "..." },
"staging": { "n8n_host": "...", "n8n_api_key": "..." }
},
"defaultEnv": "staging" // Safe default for testing
}
// Validate configuration on startup
function validateConfig(config: Config): void {
for (const [name, env] of Object.entries(config.environments)) {
if (!env.n8n_host || !env.n8n_api_key) {
throw new Error(`Invalid config for ${name}: missing required fields`);
}
if (env.n8n_host.includes('/api/v1')) {
throw new Error(`Invalid n8n_host for ${name}: remove /api/v1 suffix`);
}
}
}
// Use environment variables for sensitive data
const config = {
environments: {
production: {
n8n_host: process.env.PROD_N8N_HOST,
n8n_api_key: process.env.PROD_N8N_API_KEY
}
}
};
```
**❌ DON'T:**
```typescript
// Hardcode credentials
const apiKey = "n8n_api_key_abc123"; // Security risk!
// Include /api/v1 in configuration
"n8n_host": "https://n8n.example.com/api/v1/" // Will fail!
// Mix configuration sources
if (hasConfigJson && hasEnvFile) {
// Unclear which takes precedence
}
```
---
#### 4.2 Error Handling Best Practices
**✅ DO:**
```typescript
// Always handle errors with context
try {
const workflow = await getWorkflow({ id: '123' });
} catch (error) {
console.error('Failed to get workflow 123:', error.message);
// Provide fallback or guidance
throw new Error(`Workflow retrieval failed: ${error.message}`);
}
// Use typed error handling
if (axios.isAxiosError(error)) {
const status = error.response?.status;
if (status === 404) {
// Handle not found specifically
} else if (status === 401) {
// Handle authentication specifically
}
}
// Implement retry for transient failures
const workflow = await RetryHandler.withRetry(
() => getWorkflow({ id: '123' }),
{ maxRetries: 3, retryableErrors: [500, 502, 503] }
);
// Log errors appropriately
console.error('[ERROR] API call failed:', {
context: 'get_workflow',
workflowId: '123',
error: error.message,
timestamp: new Date().toISOString()
});
```
**❌ DON'T:**
```typescript
// Swallow errors silently
try {
await getWorkflow({ id: '123' });
} catch {
// Silent failure - impossible to debug!
}
// Expose sensitive information in errors
throw new Error(`API call failed: ${apiKey} is invalid`);
// Retry non-retryable errors
await retry(() => getWorkflow({ id: 'invalid' })); // 404 won't succeed on retry!
// Use generic error messages
throw new Error('Something went wrong'); // Unhelpful!
```
---
#### 4.3 Workflow Operation Best Practices
**✅ DO:**
```typescript
// Validate before creation
InputValidator.validateWorkflowDefinition(workflow);
// Transform connections to n8n format
workflow.connections = transformConnectionsForN8N(workflow.connections);
// Normalize Set node parameters
workflow.nodes = workflow.nodes.map(node => {
if (node.type === 'n8n-nodes-base.set') {
return { ...node, parameters: normalizeSetNodeParameters(node.parameters) };
}
return node;
});
// Add valid trigger before activation
if (workflow.active) {
await ensureValidTrigger(workflow);
}
// Use specific instance for production
await createWorkflow({ ...workflow, instance: 'production' });
// List workflows with pagination
let allWorkflows = [];
let cursor = undefined;
do {
const response = await listWorkflows({ limit: 100, cursor });
allWorkflows.push(...response.data);
cursor = response.nextCursor;
} while (cursor);
```
**❌ DON'T:**
```typescript
// Create workflow without validation
await createWorkflow(userInput); // May have invalid structure!
// Forget connection transformation
workflow.connections = arrayFormat; // n8n won't understand this!
// Use manualTrigger for active workflows
workflow.nodes = [{ type: 'n8n-nodes-base.manualTrigger', ... }];
workflow.active = true; // Will fail! (Epic 1 issue)
// Fetch all workflows without pagination
const workflows = await listWorkflows({ limit: 9999 }); // May crash!
// Modify production without instance
await updateWorkflow({ id: '123', active: false }); // Wrong instance?
```
---
#### 4.4 Credential Management Best Practices
**✅ DO:**
```typescript
// Use schema-driven creation
const schema = await getCredentialSchema({ type: 'httpBasicAuth' });
console.log('Required fields:', schema.properties.filter(p => p.required));
const credential = await createCredential({
name: 'API Credential',
type: 'httpBasicAuth',
data: {
user: process.env.API_USER,
password: process.env.API_PASSWORD
}
});
// Use DELETE + CREATE for updates
async function updateCredential(id: string, newData: any) {
await deleteCredential({ id });
return await createCredential(newData);
}
// Manage credentials through n8n UI for complex types
// (OAuth2, JWT, etc.)
```
**❌ DON'T:**
```typescript
// Try to list credentials
const creds = await listCredentials(); // Blocked by n8n!
// Try to get credential details
const cred = await getCredential({ id: '123' }); // Blocked by n8n!
// Try to update credentials directly
await updateCredential({ id: '123', data: {...} }); // Not supported!
// Hardcode credential data
const cred = await createCredential({
data: { user: 'admin', password: 'password123' } // Security risk!
});
```
---
#### 4.5 Performance Best Practices
**✅ DO:**
```typescript
// Use streamlined list_workflows (Epic 2 optimization)
const workflows = await listWorkflows({ limit: 50 }); // Metadata only
// Implement pagination for large datasets
async function getAllExecutions(workflowId: string): Promise<Execution[]> {
const executions = [];
let cursor = undefined;
do {
const response = await listExecutions({
workflowId,
limit: 100,
cursor
});
executions.push(...response.data);
cursor = response.nextCursor;
} while (cursor);
return executions;
}
// Cache frequently accessed data
const workflowCache = new Map<string, WorkflowDefinition>();
async function getCachedWorkflow(id: string): Promise<WorkflowDefinition> {
if (!workflowCache.has(id)) {
const workflow = await getWorkflow({ id });
workflowCache.set(id, workflow);
}
return workflowCache.get(id)!;
}
// Use batch operations when possible
await Promise.all(
workflowIds.map(id => activateWorkflow({ id, instance: 'production' }))
);
```
**❌ DON'T:**
```typescript
// Fetch full workflow data when only metadata needed
const workflows = await Promise.all(
ids.map(id => getWorkflow({ id })) // Wasteful for large lists!
);
// Load all executions without pagination
const executions = await listExecutions({
workflowId: '123',
limit: 99999 // May crash Claude Desktop!
});
// Make sequential API calls in loops
for (const id of workflowIds) {
await activateWorkflow({ id }); // Slow!
}
// Refetch unchanged data repeatedly
const workflow = await getWorkflow({ id: '123' }); // Every time!
```
---
### AC5: Common Mistake Prevention
**Given** developers learning the MCP server
**When** they review common mistakes
**Then** they should avoid these patterns:
#### 5.1 Top 10 Common Mistakes
**1. Including /api/v1/ in n8n_host (Epic 1)**
```typescript
// ❌ WRONG
"n8n_host": "https://n8n.example.com/api/v1/"
// ✅ CORRECT
"n8n_host": "https://n8n.example.com"
```
**2. Using manualTrigger for active workflows (Epic 1)**
```typescript
// ❌ WRONG - manualTrigger not recognized by n8n API
{
nodes: [{ type: 'n8n-nodes-base.manualTrigger', ... }],
active: true
}
// ✅ CORRECT - use scheduleTrigger or webhook
{
nodes: [{ type: 'n8n-nodes-base.scheduleTrigger', ... }],
active: true
}
```
**3. Forgetting connection format transformation**
```typescript
// ❌ WRONG - array format sent to n8n
workflow.connections = [
{ source: 'Node1', target: 'Node2' }
];
// ✅ CORRECT - transform to n8n object format
workflow.connections = transformConnectionsForN8N([
{ source: 'Node1', target: 'Node2' }
]);
```
**4. Trying to list/get credentials (Epic 2)**
```typescript
// ❌ WRONG - blocked by n8n for security
const credentials = await listCredentials();
// ✅ CORRECT - use schema-driven creation
const schema = await getCredentialSchema({ type: 'httpBasicAuth' });
const credential = await createCredential({ ...data });
```
**5. Wrong instance parameter**
```typescript
// ❌ WRONG - typo in instance name
await getWorkflow({ id: '123', instance: 'prod' }); // Should be 'production'
// ✅ CORRECT - verify instance names
const instances = envManager.listEnvironments();
console.log('Available:', instances); // ['production', 'staging']
await getWorkflow({ id: '123', instance: 'production' });
```
**6. Not handling errors**
```typescript
// ❌ WRONG - unhandled promise rejection
const workflow = await getWorkflow({ id: '123' });
// ✅ CORRECT - handle errors
try {
const workflow = await getWorkflow({ id: '123' });
} catch (error) {
console.error('Failed to get workflow:', error.message);
// Provide fallback or user guidance
}
```
**7. Loading all data without pagination**
```typescript
// ❌ WRONG - may crash with large datasets
const executions = await listExecutions({ limit: 99999 });
// ✅ CORRECT - use pagination
let cursor = undefined;
do {
const response = await listExecutions({ limit: 100, cursor });
processExecutions(response.data);
cursor = response.nextCursor;
} while (cursor);
```
**8. Trying to execute manual-trigger workflows (Epic 2)**
```typescript
// ❌ WRONG - API limitation
await executeWorkflow({ id: '123' }); // Fails if workflow has manualTrigger only
// ✅ CORRECT - check trigger type or use n8n UI
const workflow = await getWorkflow({ id: '123' });
const hasTrigger = workflow.nodes.some(n => n.type.includes('Trigger'));
if (!hasTrigger) {
console.log('Execute this workflow in n8n UI');
}
```
**9. Hardcoding credentials**
```typescript
// ❌ WRONG - security risk
const credential = await createCredential({
data: { apiKey: 'sk-abc123...' } // Exposed in code!
});
// ✅ CORRECT - use environment variables
const credential = await createCredential({
data: { apiKey: process.env.API_KEY }
});
```
**10. Not validating workflow structure**
```typescript
// ❌ WRONG - no validation
await createWorkflow(userProvidedWorkflow);
// ✅ CORRECT - validate first
InputValidator.validateWorkflowDefinition(userProvidedWorkflow);
await createWorkflow(userProvidedWorkflow);
```
---
## Dependencies
### Upstream Dependencies
- Epic 1 Story 1.1 (URL Configuration) - URL validation errors
- Epic 2 All Stories (API Validation) - API limitation documentation
- Epic 5 Story 5.1 (Multi-Instance) - Instance routing errors
- Stories 4.1-4.5 (Tool Documentation) - Tool-specific error contexts
### Downstream Dependencies
- Epic 6 (Examples & Tutorials) - Error handling examples
- Epic 7 (API Reference) - Error response schemas
- Epic 8 (Deployment) - Production error handling guides
### Cross-Story Dependencies
- All Epic 4 Stories - Error contexts for each tool category
---
## Definition of Done
### Documentation Completeness
- [ ] All error types cataloged with resolutions (15+ error types)
- [ ] 4+ troubleshooting decision trees for common scenarios
- [ ] Validation pattern library with TypeScript examples
- [ ] Best practices guide covering all tool categories
- [ ] Top 10 common mistakes documented with correct patterns
### Code Examples
- [ ] 20+ TypeScript code examples for patterns
- [ ] Error handling class implementations
- [ ] Retry logic with exponential backoff
- [ ] Input validation utilities
- [ ] Safe operation wrappers
### Cross-References
- [ ] Links to Epic 1 URL configuration issues
- [ ] Links to Epic 2 API limitations
- [ ] Links to Epic 5 multi-instance errors
- [ ] Links to Stories 4.1-4.5 for tool contexts
- [ ] Links to known issues from previous epics
### Validation
- [ ] Technical review by development team
- [ ] Error scenarios tested with actual MCP server
- [ ] Decision trees validated for correctness
- [ ] Best practices verified against production use cases
---
## Estimation Breakdown
**Story Points:** 7
**Effort Distribution:**
- Research & Error Catalog: 1.5 SP (gather all error types)
- Troubleshooting Trees: 1.5 SP (4+ decision trees)
- Validation Patterns: 1.5 SP (pattern library with code)
- Best Practices: 1.5 SP (comprehensive guide)
- Common Mistakes: 1 SP (top 10 with corrections)
**Page Count:** 12-15 pages
- Error Catalog: 4-5 pages (15+ errors)
- Decision Trees: 2-3 pages (4 trees)
- Validation Patterns: 2-3 pages (code examples)
- Best Practices: 2-3 pages (all categories)
- Common Mistakes: 1-2 pages (top 10)
**Estimated Duration:** 4-5 days (1 developer)
---
## Notes
### Success Metrics
- Developers resolve 80%+ of issues using documentation
- Decision trees lead to resolution in <5 minutes
- Common mistakes section prevents 90%+ of typical errors
- Error catalog covers all observed production errors
### Common Documentation Mistakes to Avoid
- ❌ Listing errors without resolutions
- ❌ Missing code examples for patterns
- ❌ Decision trees that don't reach resolution
- ❌ Best practices without rationale
- ❌ Incomplete error context
### Best Practices
- ✅ Provide resolution for every error type
- ✅ Include TypeScript implementations of patterns
- ✅ Decision trees with clear end states
- ✅ Best practices with DO/DON'T comparisons
- ✅ Cross-reference with epic issues
### Documentation Organization
```
docs/
└── reference/
└── error-handling-patterns.md
├── Error Catalog (15+ types)
├── Troubleshooting Trees (4+)
├── Validation Patterns
├── Best Practices
└── Common Mistakes
```
---
**Related Stories:**
- Story 4.1: Workflows Management Tools (workflow-specific errors)
- Story 4.2: Executions Management Tools (execution errors)
- Story 4.3: Tags Management Tools (tag errors)
- Story 4.4: Credentials Security Guidance (credential errors)
- Story 4.5: MCP Resources Documentation (resource errors)
**Related Epics:**
- Epic 1: URL Configuration Fix (URL validation errors)
- Epic 2: API Implementation Validation (API limitations)
- Epic 5: Multi-Instance Architecture (instance routing)
- Epic 6: Examples & Tutorials (error handling examples)
- Epic 7: API Reference Documentation (error response schemas)
