Skip to main content

​
Troubleshooting Guide

​
Quick Diagnostic Tool

NEW: Use the automated troubleshooting skill for instant diagnosis: 
/skill troubleshoot
This skill will:
  • ✅ Check PM2 worker status and health
  • ✅ Verify database existence and integrity
  • ✅ Test worker service connectivity
  • ✅ Validate dependencies installation
  • ✅ Check port configuration and availability
  • ✅ Provide automated fixes for common issues
The skill includes comprehensive diagnostics, automated repair sequences, and detailed troubleshooting workflows for all common issues. Use it before manually troubleshooting below.

​
v5.x Specific Issues

​
Viewer UI Not Loading

Symptoms: Cannot access http://localhost:37777, page doesn’t load, or shows connection error. Solutions:
  1. Check if worker is running on port 37777: 
    lsof -i :37777
# or
npm run worker:status
  2. Verify worker is healthy: 
    curl http://localhost:37777/health
  3. Check worker logs for errors: 
    npm run worker:logs
  4. Restart worker service: 
    npm run worker:restart
  5. Check for port conflicts: 
    # If port 37777 is in use by another service
export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

​
Theme Toggle Not Persisting

Symptoms: Theme preference (light/dark mode) resets after browser refresh. Solutions:
  1. Check browser localStorage is enabled: 
    // In browser console
localStorage.getItem('claude-mem-settings')
  2. Verify settings endpoint is working: 
    curl http://localhost:37777/api/settings
  3. Clear localStorage and try again: 
    // In browser console
localStorage.removeItem('claude-mem-settings')
  4. Check for browser privacy mode (blocks localStorage)

​
SSE Connection Issues

Symptoms: Viewer shows “Disconnected” status, updates not appearing in real-time. Solutions:
  1. Check SSE endpoint is accessible: 
    curl -N http://localhost:37777/stream
  2. Check browser console for errors:
    • Open DevTools (F12)
    • Look for EventSource errors
    • Check Network tab for failed /stream requests
  3. Verify worker is running: 
    npm run worker:status
  4. Check for network/proxy issues blocking SSE
    • Corporate firewalls may block SSE
    • Try disabling VPN temporarily
  5. Restart worker and refresh browser: 
    npm run worker:restart

​
Chroma/Python Dependency Issues (v5.0.0+)

Symptoms: Installation fails with chromadb or Python-related errors. Solutions:
  1. Verify Python 3.8+ is installed: 
    python --version
# or
python3 --version
  2. Install chromadb manually: 
    cd ~/.claude/plugins/marketplaces/thedotmack
npm install chromadb
  3. Check chromadb health: 
    npm run chroma:health
  4. Windows-specific: Ensure Python is in PATH: 
    where python
# Should show Python installation path
  5. If Chroma continues to fail, hybrid search will gracefully degrade to SQLite FTS5 only

​
Smart Install Caching Issues (v5.0.3+)

Symptoms: Dependencies not updating after plugin update, stale version marker. Solutions:
  1. Clear install cache: 
    rm ~/.claude/plugins/marketplaces/thedotmack/.install-version
  2. Force reinstall: 
    cd ~/.claude/plugins/marketplaces/thedotmack
npm install --force
  3. Check version marker: 
    cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version
  4. Restart Claude Code after manual install

​
PM2 ENOENT Error on Windows (v5.1.1 Fix)

Symptoms: Worker fails to start with “ENOENT” error on Windows. Solutions:
  1. This was fixed in v5.1.1 - update to latest version: 
    /plugin update claude-mem
  2. If still experiencing issues, verify PM2 path: 
    cd ~/.claude/plugins/marketplaces/thedotmack
dir node_modules\.bin\pm2.cmd
  3. Manual PM2 install if needed: 
    npm install pm2@latest

​
Worker Service Issues

​
Worker Service Not Starting

Symptoms: Worker doesn’t start, or pm2 status shows no processes. Solutions:
  1. Check if PM2 is running: 
    pm2 status
  2. Try starting manually: 
    npm run worker:start
  3. Check worker logs for errors: 
    npm run worker:logs
  4. Full reset: 
    pm2 delete claude-mem-worker
npm run worker:start
  5. Verify PM2 is installed: 
    which pm2
npm list pm2

​
Port Allocation Failed

Symptoms: Worker fails to start with “port already in use” error. Solutions:
  1. Check if port 37777 is in use: 
    lsof -i :37777
  2. Kill process using the port: 
    kill -9 $(lsof -t -i:37777)
  3. Or use a different port: 
    export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart
  4. Verify new port: 
    cat ~/.claude-mem/worker.port

​
Worker Keeps Crashing

Symptoms: Worker restarts repeatedly, PM2 shows high restart count. Solutions:
  1. Check error logs: 
    npm run worker:logs
  2. Check memory usage: 
    pm2 status
  3. Increase memory limit in ecosystem.config.cjs: 
    {
  max_memory_restart: '2G'  // Increase if needed
}
  4. Check database for corruption: 
    sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"

​
Worker Not Processing Observations

Symptoms: Observations saved but not processed, no summaries generated. Solutions:
  1. Check worker is running: 
    npm run worker:status
  2. Check worker logs: 
    npm run worker:logs
  3. Verify database has observations: 
    sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
  4. Restart worker: 
    npm run worker:restart

​
Hook Issues

​
Hooks Not Firing

Symptoms: No context appears, observations not saved. Solutions:
  1. Verify hooks are configured: 
    cat plugin/hooks/hooks.json
  2. Test hooks manually: 
    # Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js
  3. Check hook permissions: 
    ls -la plugin/scripts/*.js
  4. Verify hooks.json is valid JSON: 
    cat plugin/hooks/hooks.json | jq .

​
Context Not Appearing

Symptoms: No session context when Claude starts. Solutions:
  1. Check if summaries exist: 
    sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM session_summaries;"
  2. View recent sessions: 
    npm run test:context:verbose
  3. Check database integrity: 
    sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
  4. Manually test context hook: 
    npm run test:context

​
Hooks Timeout

Symptoms: Hook execution times out, errors in Claude Code. Solutions:
  1. Increase timeout in plugin/hooks/hooks.json: 
    {
  "timeout": 180  // Increase from 120
}
  2. Check worker is running (prevents timeout waiting for worker): 
    npm run worker:status
  3. Check database size (large database = slow queries): 
    ls -lh ~/.claude-mem/claude-mem.db
  4. Optimize database: 
    sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

​
Dependencies Not Installing

Symptoms: SessionStart hook fails with “module not found” errors. Solutions:
  1. Manually install dependencies: 
    cd ~/.claude/plugins/marketplaces/thedotmack
npm install
  2. Check npm is available: 
    which npm
npm --version
  3. Check package.json exists: 
    ls -la ~/.claude/plugins/marketplaces/thedotmack/package.json

​
Database Issues

​
Database Locked

Symptoms: “database is locked” errors in logs. Solutions:
  1. Close all connections: 
    pm2 stop claude-mem-worker
  2. Check for stale locks: 
    lsof ~/.claude-mem/claude-mem.db
  3. Kill processes holding locks: 
    kill -9 <PID>
  4. Restart worker: 
    npm run worker:start

​
Database Corruption

Symptoms: Integrity check fails, weird errors. Solutions:
  1. Check database integrity: 
    sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
  2. Backup database: 
    cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
  3. Try to repair: 
    sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
  4. Nuclear option - recreate database: 
    rm ~/.claude-mem/claude-mem.db
npm run worker:start  # Will recreate schema

​
FTS5 Search Not Working

Symptoms: Search returns no results, FTS5 errors. Solutions:
  1. Check FTS5 tables exist: 
    sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts';"
  2. Rebuild FTS5 tables: 
    sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
  INSERT INTO user_prompts_fts(user_prompts_fts) VALUES('rebuild');
"
  3. Check triggers exist: 
    sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='trigger';"

​
Database Too Large

Symptoms: Slow performance, large database file. Solutions:
  1. Check database size: 
    ls -lh ~/.claude-mem/claude-mem.db
  2. Vacuum database: 
    sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
  3. Delete old sessions: 
    sqlite3 ~/.claude-mem/claude-mem.db "
  DELETE FROM observations WHERE created_at_epoch < $(date -v-30d +%s);
  DELETE FROM session_summaries WHERE created_at_epoch < $(date -v-30d +%s);
  DELETE FROM sdk_sessions WHERE created_at_epoch < $(date -v-30d +%s);
"
  4. Rebuild FTS5 after deletion: 
    sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
"

​
MCP Search Issues

​
Search Tools Not Available

Symptoms: MCP search tools not visible in Claude Code. Solutions:
  1. Check MCP configuration: 
    cat plugin/.mcp.json
  2. Verify search server is built: 
    ls -l plugin/scripts/search-server.js
  3. Rebuild if needed: 
    npm run build
  4. Restart Claude Code

​
Search Returns No Results

Symptoms: Valid queries return empty results. Solutions:
  1. Check database has data: 
    sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
  2. Verify FTS5 tables populated: 
    sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"
  3. Test simple query: 
    # In Claude Code
search_observations with query="test"
  4. Check query syntax: 
    # Bad: Special characters
search_observations with query="[test]"

# Good: Simple words
search_observations with query="test"

​
Token Limit Errors

Symptoms: “exceeded token limit” errors from MCP. Solutions:
  1. Use index format: 
    search_observations with query="..." and format="index"
  2. Reduce limit: 
    search_observations with query="..." and limit=3
  3. Use filters to narrow results: 
    search_observations with query="..." and type="decision" and limit=5
  4. Paginate results: 
    # First page
search_observations with query="..." and limit=5 and offset=0

# Second page
search_observations with query="..." and limit=5 and offset=5

​
Performance Issues

​
Slow Context Injection

Symptoms: SessionStart hook takes too long. Solutions:
  1. Reduce context sessions: 
    // In src/hooks/context.ts
const CONTEXT_SESSIONS = 5;  // Reduce from 10
  2. Optimize database: 
    sqlite3 ~/.claude-mem/claude-mem.db "
  ANALYZE;
  VACUUM;
"
  3. Add indexes (if missing): 
    sqlite3 ~/.claude-mem/claude-mem.db "
  CREATE INDEX IF NOT EXISTS idx_sessions_project_created ON sdk_sessions(project, created_at_epoch DESC);
"

​
Slow Search Queries

Symptoms: MCP search tools take too long. Solutions:
  1. Use more specific queries
  2. Add date range filters
  3. Add type/concept filters
  4. Reduce result limit
  5. Use index format instead of full format

​
High Memory Usage

Symptoms: Worker uses too much memory, frequent restarts. Solutions:
  1. Check current usage: 
    pm2 status
  2. Increase memory limit: 
    // In ecosystem.config.cjs
{
  max_memory_restart: '2G'
}
  3. Restart worker: 
    npm run worker:restart
  4. Clean up old data (see “Database Too Large” above)

​
Installation Issues

​
Plugin Not Found

Symptoms: /plugin install claude-mem fails. Solutions:
  1. Add marketplace first: 
    /plugin marketplace add thedotmack/claude-mem
  2. Then install: 
    /plugin install claude-mem
  3. Verify installation: 
    ls -la ~/.claude/plugins/marketplaces/thedotmack/

​
Build Failures

Symptoms: npm run build fails. Solutions:
  1. Clean and reinstall: 
    rm -rf node_modules package-lock.json
npm install
  2. Check Node.js version: 
    node --version  # Should be >= 18.0.0
  3. Check for TypeScript errors: 
    npx tsc --noEmit

​
Missing Dependencies

Symptoms: “Cannot find module” errors. Solutions:
  1. Install dependencies: 
    npm install
  2. Check package.json: 
    cat package.json
  3. Verify node_modules exists: 
    ls -la node_modules/

​
Debugging

​
Enable Verbose Logging

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

​
Check Correlation IDs

Trace observations through the pipeline: 
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT correlation_id, tool_name, created_at
  FROM observations
  WHERE session_id = 'YOUR_SESSION_ID'
  ORDER BY created_at;
"

​
Inspect Worker State

# Check if worker is running
pm2 status

# View logs
pm2 logs claude-mem-worker

# Check port file
cat ~/.claude-mem/worker.port

# Test worker health
curl http://localhost:37777/health

​
Database Inspection

sqlite3 ~/.claude-mem/claude-mem.db

# View schema
.schema

# Check table counts
SELECT 'sessions', COUNT(*) FROM sdk_sessions
UNION ALL
SELECT 'observations', COUNT(*) FROM observations
UNION ALL
SELECT 'summaries', COUNT(*) FROM session_summaries
UNION ALL
SELECT 'prompts', COUNT(*) FROM user_prompts;

# View recent activity
SELECT created_at, tool_name FROM observations ORDER BY created_at DESC LIMIT 10;

​
Common Error Messages

​
”Worker service not responding”

Cause: Worker not running or port mismatch. Solution: Restart worker with npm run worker:restart.

​
”Database is locked”

Cause: Multiple processes accessing database. Solution: Stop worker, kill stale processes, restart.

​
”FTS5: syntax error”

Cause: Invalid search query syntax. Solution: Use simpler query, avoid special characters.

​
”SQLITE_CANTOPEN”

Cause: Database file permissions or missing directory. Solution: Check ~/.claude-mem/ exists and is writable.

​
”Module not found”

Cause: Missing dependencies. Solution: Run npm install.

​
Getting Help

If none of these solutions work:
  1. Check logs: 
    npm run worker:logs
  2. Create issue: GitHub Issues
    • Include error messages
    • Include relevant logs
    • Include steps to reproduce
  3. Check existing issues: Someone may have already solved your problem

​
Next Steps