Homelab/docs/guides/n8n_troubleshooting.md

# n8n Troubleshooting Guide

## Connection Loss / Frequent Disconnects

### Problem
n8n UI shows "Connection Lost" errors and logs contain:
```
ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false
```

### Root Cause
n8n is behind Traefik reverse proxy which sets `X-Forwarded-For` headers, but n8n's Express app doesn't trust the proxy by default. This breaks rate limiting and causes connection issues.

### Solution
Add these environment variables to n8n configuration:
```yaml
environment:
  - N8N_SECURE_COOKIE=false  # Required when TLS is terminated at reverse proxy
  - N8N_METRICS=true         # Enable metrics endpoint
```

**Status:** ✅ Fixed in current configuration

---

## Deprecation Warnings

### 1. SQLite Pool Size
**Warning:**
```
Running SQLite without a pool of read connections is deprecated
```

**Fix:**
```yaml
- DB_SQLITE_POOL_SIZE=10
```

### 2. Task Runners
**Warning:**
```
Running n8n without task runners is deprecated
```

**Fix:**
```yaml
- N8N_RUNNERS_ENABLED=true
```

### 3. Environment Variable Access
**Warning:**
```
The default value of N8N_BLOCK_ENV_ACCESS_IN_NODE will change from false to true
```

**Fix:**
```yaml
- N8N_BLOCK_ENV_ACCESS_IN_NODE=false  # Allow Code Node to access env vars
```

### 4. Git Node Bare Repos
**Warning:**
```
Support for bare repositories in the Git Node will be removed
```

**Fix:**
```yaml
- N8N_GIT_NODE_DISABLE_BARE_REPOS=true
```

**Status:** ✅ All fixed in current configuration

---

## Resource Issues

### Out of Memory Errors
If n8n crashes or becomes unresponsive:

**Check current limits:**
```bash
docker service inspect n8n_n8n --format '{{json .Spec.TaskTemplate.Resources}}'
```

**Recommended settings:**
```yaml
resources:
  limits:
    memory: 2G      # Increased from 1G
    cpus: '1.0'     # Increased from 0.5
  reservations:
    memory: 256M
    cpus: '0.1'
```

---

## LM Studio Connection Issues

### Problem
Workflows fail to connect to LM Studio at `http://lm-studio:1234`

### Diagnostics
```bash
# Check if extra_hosts is configured
docker service inspect n8n_n8n | grep -A 5 ExtraHosts

# Test from n8n container
docker exec $(docker ps -q -f name=n8n) curl http://lm-studio:1234/v1/models

# Test direct connection
curl http://192.168.1.81:1234/v1/models
```

### Solution
Ensure `extra_hosts` is configured in n8n-stack.yml:
```yaml
extra_hosts:
  - "lm-studio:192.168.1.81"
  - "fedora:192.168.1.81"
```

---

## Deployment

### Apply Configuration Changes
```bash
# Update the stack
docker stack deploy -c /workspace/homelab/services/swarm/stacks/n8n-stack.yml n8n

# Watch service update
docker service ps n8n_n8n --no-trunc

# Check logs
docker service logs n8n_n8n --tail 50 --follow
```

### Verify Health
```bash
# Check service status
docker service ls | grep n8n

# Test health endpoint
curl https://n8n.sj98.duckdns.org/healthz

# Check Traefik routing
docker service logs traefik_traefik --tail 20 | grep n8n
```

---

## Common Workflow Issues

### Webhook Not Triggering
1. Ensure workflow is **active** (toggle in UI)
2. Check webhook URL format: `https://n8n.sj98.duckdns.org/webhook/<webhook-id>`
3. Verify Traefik routing in logs
4. Test with curl:
   ```bash
   curl -X POST https://n8n.sj98.duckdns.org/webhook/health-check
   ```

### Execute Command Node Fails
Ensure Docker socket is mounted:
```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

### AI Node Timeout
Increase timeout in HTTP Request node options:
```json
{
  "timeout": 30000  // 30 seconds
}
```

---

## Monitoring

### Check n8n Metrics
If `N8N_METRICS=true` is set:
```bash
curl http://localhost:5678/metrics
```

### View Execution History
1. Open n8n UI
2. Go to "Executions"
3. Filter by "Failed" to see errors
4. Click execution to see detailed logs

### Resource Usage
```bash
# Container stats
docker stats $(docker ps -q -f name=n8n)

# Service resource usage
docker service ps n8n_n8n
```