Troubleshooting Mergen

Common issues and solutions for Mergen installation and operation.

🚨 Quick Fixes

Most Common Issues

📦 Installation Issues

"Command not found: mergen-server"

Cause: Package not installed globally or npx not working.

Solutions:

1. Use npx (recommended):

   npx mergen-server@latest setup
   

2. Or install globally:

   npm install -g mergen-server
   mergen-server setup
   

3. If npx fails:

   # Check npm installation
   npm --version
   
   # Update npm
   npm install -g npm@latest
   

"Port 3000 already in use"

Cause: Another service is using port 3000.

Solutions:

1. Let Mergen use another port (automatic):

   • Mergen tries ports 3000-3010
   • Check server output for actual port used

2. Kill process on port 3000:

   # macOS/Linux
   lsof -ti:3000 | xargs kill -9
   
   # Windows
   netstat -ano | findstr :3000
   taskkill /PID <PID> /F
   

3. Find what's using it:

   # macOS/Linux
   lsof -i:3000
   
   # Windows
   netstat -ano | findstr :3000
   

"npm ERR! EACCES: permission denied"

Cause: npm trying to install globally without permissions.

Solution (don't use sudo):

# Create npm global directory
mkdir ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Now install
npm install -g mergen-server

"Node.js version too old"

Cause: Mergen requires Node.js 18.17+

Solution:

# Check current version
node --version

# If < 18.17, update from:
# https://nodejs.org/

# Or use nvm:
nvm install 20
nvm use 20

🖥️ Server Issues

Server won't start

Diagnostic steps:

1. Check Node.js version:

   node --version
   # Must be >= 18.17
   

2. Check if built:

   ls server/dist/index.js
   # Should exist
   

3. Check port availability:

   lsof -i:3000
   # Should be empty or show mergen
   

Solution:

# Full rebuild
cd server
npm install
npm run build
npm start

"Health check failed"

Diagnostic:

# Test health endpoint
curl http://127.0.0.1:3000/health

# Expected response:
# {"status":"ok","version":"1.0.0",...}

If it fails:

1. Check server is running:

   ps aux | grep mergen
   

2. Check logs:

   mergen-server start
   # Look for errors in output
   

3. Try different port:

   # Server tries 3000-3010 automatically
   curl http://127.0.0.1:3001/health
   curl http://127.0.0.1:3002/health
   

Server crashes immediately

Check logs for errors:

mergen-server start 2>&1 | tee error.log

Common causes:

1. Missing dependencies:

   cd server && npm install
   

2. TypeScript not compiled:

   cd server && npm run build
   

3. Permission issues:

   # Check ~/.mergen/ permissions
   ls -la ~/.mergen/
   chmod 755 ~/.mergen/
   

🔌 Extension Issues

Extension not capturing events

Diagnostic steps:

1. Check extension is enabled:

   • Open chrome://extensions
   • Find "Mergen"
   • Toggle should be ON (blue)
   • Developer mode should be ON

2. Check server is running:

   curl http://127.0.0.1:3000/health
   

3. Check extension popup:

   • Click Mergen icon in toolbar
   • Should show "Connected" (green)
   • Check port number matches server

4. Test with manual event:

   // In browser DevTools console:
   console.error("Test error from Mergen")
   

Solutions:

1. Restart browser:

   • Close ALL browser windows
   • Reopen
   • Check extension again

2. Reload extension:

   • Go to chrome://extensions
   • Find Mergen
   • Click reload icon (circular arrow)

3. Reinstall extension:

   • Remove extension
   • Restart browser
   • Load unpacked again

Extension icon is gray (disconnected)

Cause: Extension can't reach server.

Solutions:

1. Start server:

   mergen-server start
   

2. Check port in extension:

   • Click gray icon
   • Check port number
   • Change if needed (3000-3010)

3. Check browser console:

   • Right-click extension icon
   • Inspect popup
   • Look for errors in console

Extension popup says "Wrong port"

Solution:

1. Click the port dropdown
2. Try each port 3000-3010
3. Or check server output:

   mergen-server start
   # Look for: "HTTP ingest listening on http://127.0.0.1:XXXX"
   

🤖 IDE Integration Issues

The gate isn't blocking anything

General steps:

1. Restart IDE (most common fix)
2. Run validation:

   mergen-server doctor
   

3. Check IDE-specific config below

Cursor Issues

Check configuration:

cat ~/.cursor/hooks.json
# Should have an afterFileEdit entry running `mergen-server gate-check --posthoc`

If missing, add manually:

mergen-server setup --ide=cursor

Restart Cursor after changes!

Verify:

• Edit a file to trigger a block-severity change (e.g. paste a fake secret)
• The bad content should be reverted right after it lands (detect-and-revert self-heal, not a pre-write block)

Claude Code Issues

Check configuration:

cat ~/.claude/settings.json
# Should have hooks.PreToolUse entries running `node ".../cli.js" gate-check`

If missing:

mergen-server setup --ide=claude-code

Test:

Ask Claude Code to run: terraform destroy -auto-approve. It should be blocked before it executes.

VS Code (Copilot, Cline, or any other extension) Issues

Requirements:

• The Mergen VS Code extension installed (Marketplace or Open VSX)

Plain VS Code has no AI-agent hook at the platform level, so coverage comes entirely from the Mergen extension's own document watcher (self-heal, same tier as Cursor).

If not working:

# Reinstall the extension
code --uninstall-extension mergen.mergen
code --install-extension mergen.mergen

# Restart VS Code

Verify: edit 40+ characters in a file with a block-severity change. It should be reverted.

Windsurf Issues

Check configuration:

cat ~/.codeium/windsurf/hooks.json
# Should have pre_write_code / pre_run_command entries running mergen-server gate-check

If missing:

mergen-server setup --ide=windsurf

Verify: ask Windsurf's Cascade to edit a file with a block-severity change. It should be blocked before the write happens (true pre-write block, same tier as Claude Code).

⚙️ Common Error Messages

"TypeError: fetch is not defined"

Cause: Using Node.js < 18.0 (fetch not available)

Solution:

# Check version
node --version

# Update to Node 18.17+
# Download from: https://nodejs.org/

# Or use nvm
nvm install 20
nvm use 20

"Cannot find module '@modelcontextprotocol/sdk'"

Cause: Dependencies not installed

Solution:

cd server
rm -rf node_modules package-lock.json
npm install
npm run build

"ECONNREFUSED 127.0.0.1:3000"

Cause: Server not running

Solution:

# Start server
mergen-server start

# Or check if running
ps aux | grep mergen
curl http://127.0.0.1:3000/health

"EADDRINUSE: address already in use"

Cause: Port already taken

Solution:

Server should automatically try next port. If not:

# Kill existing process
lsof -ti:3000 | xargs kill -9

# Restart server
mergen-server start

🐛 Performance Issues

High CPU usage

Diagnostic:

# Check CPU usage
top -pid $(pgrep -f mergen)

Causes:

• Too many events per second (>1000/sec)
• Large request/response bodies
• Circular references in objects

Solutions:

1. Check event rate:

   # In browser console:
   console.count("test")
   # If counting very fast (>100/sec), that's the issue
   

2. Clear buffer:

   curl -X DELETE http://127.0.0.1:3000/clear
   

3. Restart server:

   mergen-server restart
   

High memory usage

Cause: Buffer full of large events

Check:

# Monitor memory
top -pid $(pgrep -f mergen)

Normal:

• ~50-100 MB with empty buffer
• ~100-200 MB with full buffer (200 events)

If > 500 MB:

1. Clear buffer:

   curl -X DELETE http://127.0.0.1:3000/clear
   

2. Restart server:

   mergen-server restart
   

🧪 Testing & Validation

Run full diagnostics

mergen-server test

This checks:

• ✓ Server binary exists
• ✓ Server starts successfully
• ✓ Health endpoint responds
• ✓ Event ingestion works
• ✓ IDE configuration correct

If any check fails, see specific section above.

Manual pipeline test

Complete end-to-end test:

# 1. Start server
mergen-server start &
SERVER_PID=$!

# 2. Wait for startup
sleep 2

# 3. Send test event
curl -X POST http://127.0.0.1:3000/ingest \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "console",
    "level": "error",
    "args": ["Pipeline test"],
    "url": "http://test",
    "timestamp": '$(date +%s000)'
  }'

# 4. Verify event stored
curl -s http://127.0.0.1:3000/health | grep -q "Pipeline test" && echo "✓ Working" || echo "✗ Failed"

# 5. Clean up
kill $SERVER_PID

In your AI IDE, ask:

"Get recent logs"

Should see: "Pipeline test" error

🔍 Advanced Debugging

Enable debug logging

# Set debug env var
DEBUG=mergen:* mergen-server start

# Or for verbose output
NODE_ENV=development mergen-server start

Check server logs

# Real-time logs
mergen-server start | tee mergen.log

# View logs
tail -f mergen.log

# Search for errors
grep -i error mergen.log

Inspect buffer state

# Get status
curl http://127.0.0.1:3000/health | jq

# Check buffer size
curl http://127.0.0.1:3000/health | jq '.bufferedEvents'

# Get recent events
curl http://127.0.0.1:3000/logs?limit=10 | jq

Browser DevTools inspection

Check extension is working:

1. Open DevTools (F12)
2. Go to Network tab
3. Filter: localhost or 127.0.0.1
4. Trigger console.log:

   console.log("Test")
   

5. Should see: POST to http://127.0.0.1:3000/ingest

Check request:

• Status should be 200
• Request payload should contain your log

🆘 Still Stuck?

Before asking for help:

1. Run diagnostics:

   mergen-server test
   

2. Collect information:

   # System info
   echo "OS: $(uname -s)"
   echo "Node: $(node --version)"
   echo "npm: $(npm --version)"
   
   # Check server
   curl http://127.0.0.1:3000/health
   
   # Check extension
   # Open chrome://extensions, screenshot Mergen card
   

3. Check existing issues: mailto:omer@mergen.app

Get help:

For bugs: Open an issue: mailto:omer@mergen.app

Include:

• OS and version
• Node.js version
• Mergen version
• IDE and version
• Browser and version
• Steps to reproduce
• Error messages
• Output of mergen-server test
• Screenshots if applicable

For questions: Open a discussion: mailto:omer@mergen.app

Quick questions: Check FAQ.md first!

📚 Related Docs

• Installation Guide
• Quick Start
• FAQ
• Contributing