Troubleshooting

Solutions to common issues when using n8n MCP Bridge.

Connection Issues

MCP Server Not Responding

Symptoms:

• "Connection refused" errors
• "Server not responding"
• Cannot reach http://localhost:3001

Solutions:

1. Check if MCP server is running:

   curl http://localhost:3001/health

   Expected: {"status":"ok"}

2. Check Docker containers:

   docker ps

   Should show n8n-mcp-server running

3. View server logs:

   docker logs n8n-mcp-server

4. Restart services:

   task dev
   # or
   docker compose restart

Invalid API Key

Symptoms:

• "Invalid API key" error
• "Authentication failed"
• 401 Unauthorized

Solutions:

1. Verify API key format:

   • Must start with mcp_
   • Check for extra spaces
   • Ensure complete key was copied

2. Test in dashboard:

   • Go to Dashboard → API Keys
   • Find your key
   • Click "Test Connection"

3. Check key hasn't been deleted:

   • Verify key exists in dashboard
   • If not, create new key

4. Update configuration:

   • Update Claude Desktop config
   • Restart Claude
   • Test again

n8n Connection Failed

Symptoms:

• "Cannot connect to n8n"
• "n8n instance not responding"
• ping_n8n tool fails

Solutions:

1. Verify n8n is running:

   • Open n8n URL in browser
   • Should show n8n interface

2. Check n8n API key:

   • Go to n8n → Settings → API
   • Verify key is active
   • Try regenerating key

3. Test from dashboard:

   • Dashboard → Overview
   • Find n8n connection
   • Click "Test Connection"

4. Check network:

   # Test n8n URL
   curl https://n8n.example.com/health

Authentication Issues

Can't Sign In

Symptoms:

• OAuth error messages
• "Sign in failed"
• Redirect loop

Solutions:

1. Check OAuth credentials:

   • Verify GOOGLE_CLIENT_ID in .env
   • Verify GOOGLE_CLIENT_SECRET in .env
   • Same for GitHub if using

2. Verify redirect URIs:

   • Google: Must be http://localhost:3000/api/auth/callback/google
   • GitHub: Must be http://localhost:3000/api/auth/callback/github

3. Clear browser cookies:

   • Clear cookies for localhost:3000
   • Try incognito/private window

4. Check environment:

   # Verify NEXTAUTH_URL
   echo $NEXTAUTH_URL
   # Should be: http://localhost:3000

Session Expired

Symptoms:

• "Session expired" message
• Redirected to sign in repeatedly

Solutions:

1. Sign in again:

   • Sessions last 30 days
   • Simply sign in again

2. Check browser cookies:

   • Ensure cookies are enabled
   • Check cookie settings

3. Verify time sync:

   • Ensure system clock is accurate
   • JWT tokens are time-sensitive

Database Issues

Database Connection Failed

Symptoms:

• "Cannot connect to database"
• "Database unavailable"
• Application won't start

Solutions:

1. Check PostgreSQL container:

   docker ps | grep postgres

2. Verify DATABASE_URL:

   # In .env
   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/n8nmcp"

3. Test database connection:

   psql postgresql://postgres:postgres@localhost:5432/n8nmcp

4. Check database logs:

   docker logs n8n-mcp-db

Migration Errors

Symptoms:

• "Migration failed"
• "Schema mismatch"
• Database errors on startup

Solutions:

1. Run migrations:

   cd packages/web
   task db:migrate

2. Reset database (development only):

   docker compose down -v
   docker compose up -d
   task db:migrate

3. Check migration status:

   task db:studio
   # View migrations table

Build Issues

Build Failed

Symptoms:

• npm run build fails
• TypeScript errors
• Missing dependencies

Solutions:

1. Clean install:

   rm -rf node_modules
   rm -rf .next
   npm install
   npm run build

2. Check Node version:

   node --version
   # Should be 20+

3. Fix TypeScript errors:

   npm run type-check

4. Check dependencies:

   npm audit
   npm update

Fumadocs Build Error

Symptoms:

• "fumadocs-mdx" build fails
• Missing .source directory
• MDX parsing errors

Solutions:

1. Run postinstall:

   cd packages/web
   pnpm postinstall

2. Check MDX files:

   • Ensure all MDX files have valid frontmatter
   • Check for syntax errors
   • Verify meta.json files exist

3. Clean build:

   rm -rf .source
   rm -rf .next
   pnpm build

Performance Issues

Slow Response Times

Symptoms:

• Requests take > 5 seconds
• Timeouts
• Laggy UI

Solutions:

1. Check system resources:

   docker stats

2. Check n8n performance:

   • Verify n8n instance isn't overloaded
   • Check workflow complexity

3. Optimize database:

   # Clean up old logs
   DELETE FROM mcp_access_logs
   WHERE timestamp < NOW() - INTERVAL '30 days';

4. Increase Docker resources:

   • Docker Desktop → Settings → Resources
   • Increase memory/CPU allocation

High Memory Usage

Symptoms:

• Docker containers using too much memory
• System slowdown
• Out of memory errors

Solutions:

1. Check container memory:

   docker stats --no-stream

2. Restart containers:

   docker compose restart

3. Limit container memory:

   # docker-compose.yml
   services:
     app:
       mem_limit: 512m

Tool Issues

Tool Not Found

Symptoms:

• "Tool not available"
• AI can't use tools
• Tool list is empty

Solutions:

1. Check MCP server is loaded:

   • Verify in Claude Desktop settings
   • Should show "n8n" server

2. Restart AI client:

   • Quit Claude Desktop
   • Start again

3. Verify API key:

   • Test API key in dashboard
   • Ensure it's valid

Tool Execution Failed

Symptoms:

• Tool call returns error
• Unexpected results
• Timeout errors

Solutions:

1. Check tool parameters:

   • Verify parameter format
   • Check required vs optional

2. Test manually:

   curl -X POST http://localhost:3001/mcp?apiKey=mcp_key \
     -H "Content-Type: application/json" \
     -d '{"method":"tools/call","params":{"name":"ping_n8n"}}'

3. Check logs:

   docker logs n8n-mcp-server

Getting More Help

Enable Debug Logging

Add to .env:

LOG_LEVEL=debug

Restart services:

task dev

Check Logs

# All services
docker compose logs -f

# Specific service
docker logs -f n8n-mcp-server
docker logs -f n8n-mcp-app
docker logs -f n8n-mcp-db

Report an Issue

If you've tried everything:

1. Gather information:

   • Error messages
   • Logs
   • Configuration (remove secrets!)
   • Steps to reproduce

2. Check existing issues:

   • GitHub Issues

3. Create new issue:

   • Describe problem
   • Include error logs
   • Explain what you've tried

Common Error Messages

Error	Meaning	Solution
ECONNREFUSED	Can't connect to service	Check service is running
Invalid API key	API key not recognized	Verify key in dashboard
Database unavailable	PostgreSQL not running	Check database container
n8n connection failed	Can't reach n8n	Verify n8n URL and API key
Session expired	Login session ended	Sign in again
CORS error	Cross-origin issue	Check NEXTAUTH_URL setting
Build failed	Compilation error	Check TypeScript errors

Next Steps

• View API Reference →
• Read Getting Started →
• Browse Features →