Symptom: MCP tools return errors, CLI says broker is not running.

Fix:

# Check if broker is running
slm-mesh status
# If not, start it manually
slm-mesh start
# Or just run any MCP command — it auto-starts the broker

Symptom: Broker fails to start with "EADDRINUSE" error.

Fix: The broker automatically tries ports 7899-7909. If all are busy:

# Find what's using the port
lsof -i :7899
# Kill the old process, or set a different port
SLM_MESH_PORT=8899 slm-mesh start

Symptom: slm-mesh status says broker is running but nothing works.

Fix:

slm-mesh clean # Kills zombie processes and cleans stale sockets
slm-mesh start # Restart fresh

Symptom: Agent loses SLM Mesh tools after a few seconds.

Fix: Check that the broker is accessible:

curl http://127.0.0.1:7899/health
# Should return: {"status":"ok","version":"1.0.0",...}

If it works via curl but not via MCP, check your MCP configuration syntax.

Symptom: Sending a message returns this error.

Causes:

1. The target peer closed their session
2. The target peer's heartbeat expired (crash without clean exit)
3. You are using an old peer ID

Fix: Call mesh_peers to get fresh peer IDs.

Symptom: A file lock persists after the session that created it ended.

Fix: Locks auto-expire after the TTL (default: 10 minutes). If you need to clear immediately:

# Via CLI (if you know the peer ID)
slm-mesh lock list # Find the lock
# The lock will expire on its own
# Or restart the broker (clears all state)
slm-mesh stop && slm-mesh start

Symptom: Python processes consuming gigabytes of memory.

Note: This is a SuperLocalMemory issue, not SLM Mesh. If SLM auto-observe hooks are triggering many embedding workers:

# Disable SLM hooks temporarily
touch ~/.superlocalmemory/.hooks-disabled
# Kill existing workers
pkill -f "embedding_worker"

Symptom: CLI or MCP tools return "Unauthorized" errors.

Cause: The broker token was regenerated (broker restarted) but the client cached the old token.

Fix: The CLI and MCP server read the token from disk on each request, so this should auto-resolve. If not:

# Check the token file exists
cat ~/.slm-mesh/broker.token
# Restart your AI agent session to force re-registration

# Full system check
slm-mesh status --json
# Check active peers
slm-mesh peers --json
# Check active locks
slm-mesh lock list --json
# Check recent events
slm-mesh events --json
# Clean up zombie processes
slm-mesh clean

Broker logs are at ~/.slm-mesh/broker.log. They include:

• Startup and shutdown events
• Peer registration and deregistration
• Error details
• Heartbeat failures

tail -f ~/.slm-mesh/broker.log

Open an issue at github.com/qualixar/slm-mesh/issues.