Debug Mode & Logging Guide¶

Complete guide to debug mode, logging system, and debugging workflows for the n8n MCP Workflow Builder.

Quick Start¶

Enable debug mode to see detailed logs:

# Start with debug mode
DEBUG=true npm start

# Or for specific port
DEBUG=true MCP_PORT=58921 npm start

What you'll see: - Configuration loading details - URL normalization logs - API request/response information - Instance routing decisions - Error stack traces

Enabling Debug Mode¶

Development Environment¶

Option 1: Environment Variable

# Enable debug mode
DEBUG=true npm start

# With custom port
DEBUG=true MCP_PORT=58921 npm start

# With other environment variables
DEBUG=true N8N_HOST=https://n8n.example.com N8N_API_KEY=key npm start

Option 2: In .env File

# Create or edit .env
echo "DEBUG=true" >> .env

# Then start normally
npm start

Option 3: Export Environment Variable

# Set for current session
export DEBUG=true
npm start

# Unset when done
unset DEBUG

Claude Desktop Configuration¶

Add DEBUG to environment variables in claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "DEBUG": "true",
        "N8N_HOST": "https://n8n.example.com",
        "N8N_API_KEY": "your_api_key",
        "MCP_PORT": "58921"
      }
    }
  }
}

Restart Required: - Quit Claude Desktop completely - Relaunch to apply debug mode

Production Environment¶

⚠️ Warning: Debug mode generates verbose logs. Use with caution in production.

Recommended Approach:

# Enable temporarily for troubleshooting
DEBUG=true npm start

# Disable after debugging
npm start

Alternative: Log to File

# Redirect debug logs to file
DEBUG=true npm start 2> debug.log

# Monitor logs
tail -f debug.log

Log Levels & Categories¶

Log Levels¶

All MCP logs use console.error() to avoid interfering with JSON-RPC on stdout.

Level	Description	When Used
info	General information	Startup, configuration loaded, instance routing
error	Error messages	API failures, validation errors, crashes
debug	Debug information	Only when `DEBUG=true`
warn	Warning messages	Deprecation notices, potential issues

Log Categories¶

Configuration Loading:

[ConfigLoader] Loading configuration...
[ConfigLoader] Using .config.json (multi-instance mode)
[ConfigLoader] Loaded 3 environments: production, staging, development
[ConfigLoader] Default environment: production

Environment Manager:

[EnvironmentManager] Initializing for instance: production
[EnvironmentManager] Original URL: https://n8n.example.com/api/v1/
[EnvironmentManager] Normalized baseURL: https://n8n.example.com/api/v1
[EnvironmentManager] API instance cached for: production

API Wrapper:

[N8NApiWrapper] Calling list_workflows for instance: production
[N8NApiWrapper] Request: GET /workflows?limit=10
[N8NApiWrapper] Response: 200 OK (123ms)
[N8NApiWrapper] Retrieved 10 workflows

MCP Server:

[MCP] Server initialized on port 58921
[MCP] Tool called: list_workflows
[MCP] Tool execution successful: list_workflows (234ms)
[MCP] Resource requested: n8n://workflows

Error Logs:

[ERROR] API error during list_workflows
[ERROR] Status: 401
[ERROR] Response: {"code":401,"message":"Unauthorized"}

Reading Logs¶

Log Format¶

[Category] Message with details

Examples:

[ConfigLoader] Configuration loaded successfully
[EnvironmentManager] Using instance: production
[N8NApiWrapper] API call successful: GET /workflows
[MCP] Tool executed: create_workflow (1.2s)
[ERROR] Authentication failed: Invalid API key

Timestamp Analysis¶

Logs include execution time in parentheses for performance monitoring:

[N8NApiWrapper] Response: 200 OK (45ms)
[MCP] Tool execution successful: list_workflows (234ms)

Performance Indicators: - < 100ms - Excellent (cached or simple operation) - 100-500ms - Good (typical API call) - 500-2000ms - Acceptable (complex operation) - > 2000ms - Slow (investigate)

Error Stack Traces¶

When DEBUG=true, errors include full stack traces:

[ERROR] API error during list_workflows
Error: Request failed with status code 401
    at N8NApiWrapper.handleApiError (N8NApiWrapper.ts:123)
    at N8NApiWrapper.listWorkflows (N8NApiWrapper.ts:234)
    at processTicksAndRejections (internal/process/task_queues.js:93)
[ERROR] Status: 401
[ERROR] Response: {"code":401,"message":"Invalid credentials"}

Reading Stack Traces: 1. Error message - What went wrong 2. Status code - HTTP status (401 = auth, 404 = not found, etc.) 3. Stack trace - Where error originated 4. Response body - n8n API error details

Common Log Patterns¶

Successful Tool Execution¶

[MCP] Tool called: list_workflows
[N8NApiWrapper] Calling list_workflows for instance: production
[EnvironmentManager] Using cached API instance for: production
[N8NApiWrapper] Request: GET /workflows?limit=10
[N8NApiWrapper] Response: 200 OK (87ms)
[N8NApiWrapper] Retrieved 10 workflows
[MCP] Tool execution successful: list_workflows (145ms)

Indicators: - ✅ 200 OK status - ✅ Response time < 500ms - ✅ Expected data retrieved - ✅ No error messages

API Call Failure¶

[MCP] Tool called: list_workflows
[N8NApiWrapper] Calling list_workflows for instance: production
[N8NApiWrapper] Request: GET /workflows
[ERROR] API error during list_workflows
[ERROR] Status: 401
[ERROR] Response: {"code":401,"message":"Unauthorized"}
Error: Request failed with status code 401
    at N8NApiWrapper.handleApiError (...)

Indicators: - ❌ 401 Unauthorized (invalid API key) - ❌ 404 Not Found (wrong URL or resource) - ❌ 500 Internal Server Error (n8n issue) - ❌ ECONNREFUSED (n8n not reachable)

URL Normalization (Epic 1)¶

[EnvironmentManager] Initializing for instance: production
[EnvironmentManager] Original URL: https://n8n.example.com/api/v1/
[EnvironmentManager] URL includes /api/v1, normalizing...
[EnvironmentManager] Normalized baseURL: https://n8n.example.com/api/v1

What this means: - Automatic removal of duplicate /api/v1 paths - Ensures correct API endpoint construction - Prevents 404 errors from malformed URLs

Instance Routing Logs¶

[ConfigLoader] Loaded 3 environments: production, staging, development
[ConfigLoader] Default environment: production
[MCP] Tool called: list_workflows (instance: staging)
[EnvironmentManager] Resolving instance: staging
[EnvironmentManager] Using cached API instance for: staging

Instance Selection: - Explicit instance parameter → Use specified instance - No instance parameter → Use default environment - Invalid instance → Error with available instances list

Configuration Loading¶

[ConfigLoader] Loading configuration...
[ConfigLoader] Checking for .config.json...
[ConfigLoader] Found .config.json
[ConfigLoader] Using .config.json (multi-instance mode)
[ConfigLoader] Loaded 3 environments: production, staging, development
[ConfigLoader] Default environment: production
[ConfigLoader] Configuration loaded successfully

Fallback Order: 1. .config.json (multi-instance) 2. .env file (single instance) 3. Environment variables

Debugging Workflows¶

Installation Debugging¶

Enable debug mode and check startup:

DEBUG=true npm start

Expected Output:

[ConfigLoader] Loading configuration...
[ConfigLoader] Configuration loaded successfully
[MCP] Server initialized on port 58921
[MCP] Listening for MCP requests...

Common Issues:

Missing configuration:

[ERROR] Configuration file not found
[ERROR] Please create .config.json or .env file

Solution: Create configuration file

Invalid JSON:

[ERROR] Failed to parse .config.json
SyntaxError: Unexpected token } in JSON at position 123

Solution: Validate JSON syntax

Port conflict:

[ERROR] Port 3456 already in use

Solution: Use MCP_PORT=58921 or kill process on port 3456

Configuration Debugging¶

Check configuration loading:

DEBUG=true npm start

Look for:

[ConfigLoader] Using .config.json (multi-instance mode)
[ConfigLoader] Loaded environments: production, staging, development
[ConfigLoader] Default environment: production

Verify URL normalization:

[EnvironmentManager] Original URL: https://n8n.example.com/api/v1/
[EnvironmentManager] Normalized baseURL: https://n8n.example.com/api/v1

Test API connectivity:

[N8NApiWrapper] Request: GET /workflows?limit=1
[N8NApiWrapper] Response: 200 OK

Runtime Debugging¶

Monitor tool execution:

DEBUG=true npm start

Watch for:

[MCP] Tool called: create_workflow
[N8NApiWrapper] Calling create_workflow for instance: production
[N8NApiWrapper] Request: POST /workflows
[N8NApiWrapper] Request body: {...}
[N8NApiWrapper] Response: 201 Created (456ms)
[MCP] Tool execution successful: create_workflow (523ms)

Debug specific operations:

list_workflows:

[N8NApiWrapper] Request: GET /workflows?limit=10&cursor=abc123
[N8NApiWrapper] Response: 200 OK (123ms)
[N8NApiWrapper] Retrieved 10 workflows, nextCursor: def456

activate_workflow:

[N8NApiWrapper] Activating workflow 123
[N8NApiWrapper] Checking for valid trigger nodes...
[N8NApiWrapper] Found trigger: scheduleTrigger
[N8NApiWrapper] Request: PATCH /workflows/123
[N8NApiWrapper] Response: 200 OK

Performance Debugging¶

Identifying Slow Operations¶

Enable debug mode and monitor execution times:

DEBUG=true npm start

Look for slow operations:

[N8NApiWrapper] Response: 200 OK (2345ms)  # > 2 seconds!

Common Slow Operations:

Large workflow lists (without pagination):

[N8NApiWrapper] Request: GET /workflows  # No limit!
[N8NApiWrapper] Response: 200 OK (5678ms)  # Very slow

Solution: Use pagination with limit and cursor

Retrieving full workflow data:

[N8NApiWrapper] Request: GET /workflows/123
[N8NApiWrapper] Response: 200 OK (3456ms)  # Large workflow

Solution: Use metadata-only list first, fetch details only when needed

API Response Time Analysis¶

Measure API performance:

DEBUG=true npm start 2>&1 | grep "Response:"

Output:

[N8NApiWrapper] Response: 200 OK (45ms)
[N8NApiWrapper] Response: 200 OK (123ms)
[N8NApiWrapper] Response: 200 OK (2345ms)  # Outlier!

Performance Thresholds: - < 100ms - Cached or simple operation ✅ - 100-500ms - Normal API call ✅ - 500-2000ms - Complex operation ⚠️ - > 2000ms - Performance issue ❌

Memory Usage Patterns¶

Monitor memory with Node.js flags:

DEBUG=true node --trace-warnings --expose-gc build/index.js

Look for: - Memory leaks (increasing memory over time) - Large object allocations - GC (garbage collection) pauses

Connection Pooling Metrics¶

Check API instance caching:

DEBUG=true npm start 2>&1 | grep "API instance"

Expected:

[EnvironmentManager] API instance created for: production
[EnvironmentManager] Using cached API instance for: production  # Reuse!
[EnvironmentManager] Using cached API instance for: production  # Reuse!

Performance Impact: - First call: Instance creation (~50ms overhead) - Subsequent calls: Cached instance (~0ms overhead) - ~100x faster for repeated operations

Network Debugging¶

Request/Response Inspection¶

Enable debug mode to see all HTTP traffic:

DEBUG=true npm start

Full request details:

[N8NApiWrapper] Request: POST /workflows
[N8NApiWrapper] URL: https://n8n.example.com/api/v1/workflows
[N8NApiWrapper] Headers: {
  "X-N8N-API-KEY": "***",  # Redacted in logs
  "Content-Type": "application/json"
}
[N8NApiWrapper] Request body: {
  "name": "My Workflow",
  "nodes": [...],
  "connections": {...}
}

Response details:

[N8NApiWrapper] Response: 201 Created (456ms)
[N8NApiWrapper] Response body: {
  "id": "123",
  "name": "My Workflow",
  "active": false,
  "createdAt": "2025-01-15T10:00:00Z"
}

URL Construction Verification¶

Check final API URLs:

DEBUG=true npm start 2>&1 | grep "URL:"

Output:

[N8NApiWrapper] URL: https://n8n.example.com/api/v1/workflows
[N8NApiWrapper] URL: https://n8n.example.com/api/v1/workflows/123
[N8NApiWrapper] URL: https://n8n.example.com/api/v1/executions?workflowId=123

Verify: - ✅ No duplicate /api/v1 paths - ✅ Correct protocol (http/https) - ✅ Correct domain - ✅ Proper query parameters

Authentication Header Checking¶

Verify API key is sent:

DEBUG=true npm start 2>&1 | grep "Headers:"

Expected:

[N8NApiWrapper] Headers: {
  "X-N8N-API-KEY": "***",  # Present and redacted
  "Content-Type": "application/json"
}

Issues: - Missing X-N8N-API-KEY → API key not configured - Wrong header name → Check n8n API version

Proxy/Firewall Detection¶

Test connectivity:

# Enable verbose curl output
curl -v https://your-n8n-host/api/v1/workflows \
  -H "X-N8N-API-KEY: your_key"

Look for:

* Connected to your-n8n-host (IP) port 443 (#0)
* TLS handshake succeeded
> GET /api/v1/workflows HTTP/1.1
> Host: your-n8n-host
> X-N8N-API-KEY: your_key

< HTTP/1.1 200 OK

Common Issues: - Connection refused → Firewall blocking - Connection timeout → Network issue - SSL handshake failed → Certificate issue - 407 Proxy Authentication Required → Proxy issue

SSL/TLS Troubleshooting¶

Check certificate:

openssl s_client -connect your-n8n-host:443 -servername your-n8n-host

Look for:

Verify return code: 0 (ok)  # ✅ Valid certificate
Verify return code: 19 (self signed certificate)  # ⚠️ Self-signed
Verify return code: 10 (certificate has expired)  # ❌ Expired

For development with self-signed certificates:

# DEVELOPMENT ONLY - Disable SSL verification
NODE_TLS_REJECT_UNAUTHORIZED=0 DEBUG=true npm start

⚠️ Never use in production!

Multi-Instance Debugging¶

Instance Selection Logging¶

Monitor instance routing:

DEBUG=true npm start 2>&1 | grep "instance"

Output:

[ConfigLoader] Loaded 3 environments: production, staging, development
[MCP] Tool called: list_workflows (instance: production)
[EnvironmentManager] Resolving instance: production
[EnvironmentManager] Using cached API instance for: production

Verify: - ✅ Correct instance selected - ✅ Instance exists in configuration - ✅ API instance cached for performance

Environment Routing Traces¶

Full routing flow:

[MCP] Tool called: create_workflow
[MCP] Parameters: { instance: "staging", name: "Test Workflow", ... }
[EnvironmentManager] Resolving instance: staging
[EnvironmentManager] Instance found in configuration
[EnvironmentManager] Creating API instance for: staging
[EnvironmentManager] Base URL: https://staging.n8n.example.com/api/v1
[EnvironmentManager] API instance cached for: staging
[N8NApiWrapper] Calling create_workflow for instance: staging

Configuration Per Instance¶

Check instance-specific settings:

DEBUG=true npm start

Look for:

[ConfigLoader] Environment: production
[ConfigLoader]   - Host: https://prod.n8n.example.com
[ConfigLoader]   - API Key: *** (redacted)

[ConfigLoader] Environment: staging
[ConfigLoader]   - Host: https://staging.n8n.example.com
[ConfigLoader]   - API Key: *** (redacted)

API Instance Caching Logs¶

Monitor cache effectiveness:

DEBUG=true npm start 2>&1 | grep "API instance"

Expected pattern:

[EnvironmentManager] API instance created for: production  # First call
[EnvironmentManager] Using cached API instance for: production  # Subsequent
[EnvironmentManager] Using cached API instance for: production  # Subsequent
[EnvironmentManager] API instance created for: staging  # First for staging
[EnvironmentManager] Using cached API instance for: staging  # Subsequent

Benefits: - ~100x faster subsequent calls - Reduced connection overhead - Better performance for repeated operations

Advanced Debugging Techniques¶

Logging to File¶

Capture all debug logs:

# All logs to file
DEBUG=true npm start 2> debug.log

# Monitor in real-time
tail -f debug.log

Filter specific categories:

# Only configuration logs
DEBUG=true npm start 2>&1 | grep "ConfigLoader"

# Only API calls
DEBUG=true npm start 2>&1 | grep "N8NApiWrapper"

# Only errors
DEBUG=true npm start 2>&1 | grep "ERROR"

Verbose Curl Testing¶

Test n8n API directly:

# Verbose output
curl -v https://your-n8n-host/api/v1/workflows \
  -H "X-N8N-API-KEY: your_key" \
  2>&1 | tee curl-debug.log

# Analyze timing
curl -w "\nTime: %{time_total}s\n" \
  https://your-n8n-host/api/v1/workflows \
  -H "X-N8N-API-KEY: your_key"

Node.js Debug Flags¶

Advanced debugging:

# Trace warnings
node --trace-warnings build/index.js

# Trace deprecations
node --trace-deprecation build/index.js

# Enable async stack traces
node --async-stack-traces build/index.js

# Combine with DEBUG
DEBUG=true node --trace-warnings build/index.js

Memory Profiling¶

Check for memory leaks:

# Enable GC logging
node --expose-gc --trace-gc build/index.js

# Heap snapshot
node --inspect build/index.js
# Then use Chrome DevTools Memory profiler

Debugging Checklists¶

Quick Diagnostic Checklist¶

When something isn't working:

Enable debug mode:
```
DEBUG=true npm start
```
Check startup logs:
Configuration loaded?
Correct environments?
Server started on expected port?
Check instance routing:
Correct instance selected?
Instance exists in configuration?
API instance cached?
Check API calls:
Correct URL constructed?
API key sent?
Response status 200/201?
Check error messages:
Error category identified?
Stack trace available?
n8n API error details?

Performance Debugging Checklist¶

When operations are slow:

Measure response times:

DEBUG=true npm start 2>&1 | grep "Response:"

Check for:
Slow API calls (> 2 seconds)
Network timeouts
Large data transfers
Missing pagination
Optimize:
Use pagination for lists
Fetch metadata before full data
Check n8n instance performance
Verify network connection

Connection Debugging Checklist¶

When can't connect to n8n:

Test n8n accessibility:
```
curl -I https://your-n8n-host
```
Check:
n8n instance running?
URL correct (no /api/v1 suffix)?
Firewall allowing connection?
VPN connected (if required)?

Test API endpoint:

curl https://your-n8n-host/api/v1/workflows \
  -H "X-N8N-API-KEY: your_key"

Verify:
Returns 200 OK (not 401/404)
Returns workflow list JSON
No network errors

Next Steps¶

Still having issues?

Enable debug mode and capture logs
Review Error Reference for specific errors
Check FAQ for common questions
Test components systematically
Report issues with debug logs

Related Documentation: - Error Reference - Specific error solutions - FAQ - Common questions - Testing Guide - Test infrastructure - Contributing - Report bugs

Document Version: 1.0 Last Updated: December 2025 Related: Error Reference, FAQ, Testing