# 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:

```bash
# 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

---

## Table of Contents

1. [Enabling Debug Mode](#enabling-debug-mode)
2. [Log Levels & Categories](#log-levels--categories)
3. [Reading Logs](#reading-logs)
4. [Common Log Patterns](#common-log-patterns)
5. [Debugging Workflows](#debugging-workflows)
6. [Performance Debugging](#performance-debugging)
7. [Network Debugging](#network-debugging)
8. [Multi-Instance Debugging](#multi-instance-debugging)

---

## Enabling Debug Mode

### Development Environment

**Option 1: Environment Variable**
```bash
# 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**
```bash
# Create or edit .env
echo "DEBUG=true" >> .env

# Then start normally
npm start
```

**Option 3: Export Environment Variable**
```bash
# 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`:

```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:**
```bash
# Enable temporarily for troubleshooting
DEBUG=true npm start

# Disable after debugging
npm start
```

**Alternative: Log to File**
```bash
# 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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
# 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:**

```bash
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:**
```bash
# 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:**

```bash
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:**

```bash
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:**

```bash
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:**

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

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

**Filter specific categories:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

1. **Enable debug mode:**
   ```bash
   DEBUG=true npm start
   ```

2. **Check startup logs:**
   - [ ] Configuration loaded?
   - [ ] Correct environments?
   - [ ] Server started on expected port?

3. **Check instance routing:**
   - [ ] Correct instance selected?
   - [ ] Instance exists in configuration?
   - [ ] API instance cached?

4. **Check API calls:**
   - [ ] Correct URL constructed?
   - [ ] API key sent?
   - [ ] Response status 200/201?

5. **Check error messages:**
   - [ ] Error category identified?
   - [ ] Stack trace available?
   - [ ] n8n API error details?

### Performance Debugging Checklist

**When operations are slow:**

1. **Measure response times:**
   ```bash
   DEBUG=true npm start 2>&1 | grep "Response:"
   ```

2. **Check for:**
   - [ ] Slow API calls (> 2 seconds)
   - [ ] Network timeouts
   - [ ] Large data transfers
   - [ ] Missing pagination

3. **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:**

1. **Test n8n accessibility:**
   ```bash
   curl -I https://your-n8n-host
   ```

2. **Check:**
   - [ ] n8n instance running?
   - [ ] URL correct (no /api/v1 suffix)?
   - [ ] Firewall allowing connection?
   - [ ] VPN connected (if required)?

3. **Test API endpoint:**
   ```bash
   curl https://your-n8n-host/api/v1/workflows \
     -H "X-N8N-API-KEY: your_key"
   ```

4. **Verify:**
   - [ ] Returns 200 OK (not 401/404)
   - [ ] Returns workflow list JSON
   - [ ] No network errors

---

## Next Steps

**Still having issues?**

1. **Enable debug mode** and capture logs
2. **Review [Error Reference](error-reference.md)** for specific errors
3. **Check [FAQ](faq.md)** for common questions
4. **Test components** systematically
5. **Report issues** with debug logs

**Related Documentation:**
- [Error Reference](error-reference.md) - Specific error solutions
- [FAQ](faq.md) - Common questions
- [Testing Guide](testing.md) - Test infrastructure
- [Contributing](../about/contributing.md) - Report bugs

---

**Document Version:** 1.0
**Last Updated:** December 2025
**Related:** [Error Reference](error-reference.md), [FAQ](faq.md), [Testing](testing.md)