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 OmerTahtaci.mergen
code --install-extension OmerTahtaci.mergen

# Restart VS Code

If you installed from Open VSX (Cursor, Windsurf, VSCodium) rather than the Microsoft Marketplace, the extension is registered under mergen.mergen instead, so use that id in the commands above. code --list-extensions | grep -i mergen shows which one you have.

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
   

Get help:

For bugs: Email 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

Quick questions: Check FAQ.md first!

📚 Related Docs

• Quick Start
• FAQ
• CLI Reference