claude-mem/docs/public/troubleshooting.mdx

---
title: "Troubleshooting"
description: "Common issues and solutions for Claude-Mem"
---

# Troubleshooting Guide

## Quick Diagnostic Tool

Describe any issues you're experiencing to Claude, and the troubleshoot skill will automatically activate to provide diagnosis and fixes.

The troubleshoot skill will:
- ✅ Check 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. Simply describe the problem naturally to invoke it.

---

## 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:
   ```bash
   lsof -i :37777
   # or
   npm run worker:status
   ```

2. Verify worker is healthy:
   ```bash
   curl http://localhost:37777/health
   ```

3. Check worker logs for errors:
   ```bash
   npm run worker:logs
   ```

4. Restart worker service:
   ```bash
   npm run worker:restart
   ```

5. Check for port conflicts:
   ```bash
   # 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:
   ```javascript
   // In browser console
   localStorage.getItem('claude-mem-settings')
   ```

2. Verify settings endpoint is working:
   ```bash
   curl http://localhost:37777/api/settings
   ```

3. Clear localStorage and try again:
   ```javascript
   // 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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   python --version
   # or
   python3 --version
   ```

2. Install chromadb manually:
   ```bash
   cd ~/.claude/plugins/marketplaces/thedotmack
   npm install chromadb
   ```

3. Check chromadb health:
   ```bash
   npm run chroma:health
   ```

4. Windows-specific: Ensure Python is in PATH:
   ```bash
   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:
   ```bash
   rm ~/.claude/plugins/marketplaces/thedotmack/.install-version
   ```

2. Force reinstall:
   ```bash
   cd ~/.claude/plugins/marketplaces/thedotmack
   npm install --force
   ```

3. Check version marker:
   ```bash
   cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
   cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version
   ```

4. Restart Claude Code after manual install


## Worker Service Issues

### Worker Service Not Starting

**Symptoms**: Worker doesn't start, or worker status shows it's not running.

**Solutions**:

1. Check worker status:
   ```bash
   npm run worker:status
   ```

2. Try starting manually:
   ```bash
   npm run worker:start
   ```

3. Check worker logs for errors:
   ```bash
   npm run worker:logs
   ```

4. Full reset:
   ```bash
   npm run worker:stop
   npm run worker:start
   ```

5. Verify Bun is installed:
   ```bash
   which bun
   bun --version
   ```

### Port Allocation Failed

**Symptoms**: Worker fails to start with "port already in use" error.

**Solutions**:

1. Check if port 37777 is in use:
   ```bash
   lsof -i :37777
   ```

2. Kill process using the port:
   ```bash
   kill -9 $(lsof -t -i:37777)
   ```

3. Or use a different port:
   ```bash
   export CLAUDE_MEM_WORKER_PORT=38000
   npm run worker:restart
   ```

4. Verify new port:
   ```bash
   cat ~/.claude-mem/worker.port
   ```

### Worker Keeps Crashing

**Symptoms**: Worker restarts repeatedly or fails to stay running.

**Solutions**:

1. Check error logs:
   ```bash
   npm run worker:logs
   ```

2. Check worker status:
   ```bash
   npm run worker:status
   ```

3. Check database for corruption:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

4. Verify Bun installation:
   ```bash
   bun --version
   ```

### Worker Not Processing Observations

**Symptoms**: Observations saved but not processed, no summaries generated.

**Solutions**:

1. Check worker is running:
   ```bash
   npm run worker:status
   ```

2. Check worker logs:
   ```bash
   npm run worker:logs
   ```

3. Verify database has observations:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   ```

4. Restart worker:
   ```bash
   npm run worker:restart
   ```

### Manual Recovery for Stuck Observations

**Symptoms**: Observations stuck in processing queue after worker crash or restart, no new summaries appearing despite worker running.

**Background**: As of v5.x, automatic queue recovery on worker startup is disabled. Users must manually trigger recovery to maintain explicit control over reprocessing and prevent unexpected duplicate observations.

**Solutions**:

#### Option 1: Use CLI Recovery Tool (Recommended)

The interactive CLI tool provides the safest and most user-friendly recovery experience:

```bash
# Check queue status and prompt for recovery
bun scripts/check-pending-queue.ts

# Auto-process without prompting
bun scripts/check-pending-queue.ts --process

# Process up to 5 sessions
bun scripts/check-pending-queue.ts --process --limit 5
```

**What it does**:
- ✅ Checks worker health before proceeding
- ✅ Shows detailed queue summary (pending, processing, failed, stuck)
- ✅ Groups messages by session with age and status breakdown
- ✅ Prompts user to confirm processing (unless `--process` flag used)
- ✅ Shows recently processed messages for feedback

**Interactive Example**:
```
Worker is healthy ✓

Queue Summary:
  Pending: 12 messages
  Processing: 2 messages (1 stuck)
  Failed: 0 messages
  Recently Processed: 5 messages in last 30 minutes

Sessions with pending work: 3
  Session 44: 5 pending, 1 processing (age: 2m)
  Session 45: 4 pending, 1 processing (age: 7m - STUCK)
  Session 46: 2 pending

Would you like to process these pending queues? (y/n)
```

#### Option 2: Use HTTP API Directly

For automation or scripting scenarios:

1. **Check queue status**:
   ```bash
   curl http://localhost:37777/api/pending-queue
   ```

   Response shows:
   - `queue.totalPending`: Messages waiting to process
   - `queue.totalProcessing`: Messages currently processing
   - `queue.stuckCount`: Processing messages >5 minutes old
   - `sessionsWithPendingWork`: Session IDs needing recovery

2. **Trigger manual recovery**:
   ```bash
   curl -X POST http://localhost:37777/api/pending-queue/process \
     -H "Content-Type: application/json" \
     -d '{"sessionLimit": 10}'
   ```

   Response includes:
   - `totalPendingSessions`: Total sessions with pending messages
   - `sessionsStarted`: Number of sessions we started processing
   - `sessionsSkipped`: Sessions already processing (not restarted)
   - `startedSessionIds`: Database IDs of sessions started

#### Understanding Queue States

Messages progress through these states:

1. **pending** - Queued, waiting to process
2. **processing** - Currently being processed by SDK agent
3. **processed** - Completed successfully
4. **failed** - Failed after 3 retry attempts

**Stuck Detection**: Messages in `processing` state for >5 minutes are considered stuck and automatically reset to `pending` on worker startup (but not automatically reprocessed).

#### Recovery Strategy

**When to use manual recovery**:
- After worker crashes or unexpected restarts
- When observations appear saved but no summaries generated
- When queue status shows stuck messages (processing >5 minutes)
- After system crashes or forced shutdowns

**Best practices**:
1. Always check queue status before triggering recovery
2. Use the CLI tool for interactive sessions (provides feedback)
3. Use the HTTP API for automation/scripting
4. Start with a low session limit (5-10) to avoid overwhelming the worker
5. Monitor worker logs during recovery: `npm run worker:logs`
6. Check recently processed messages to confirm recovery worked

#### Troubleshooting Recovery Issues

If recovery fails or messages remain stuck:

1. **Verify worker is healthy**:
   ```bash
   curl http://localhost:37777/health
   # Should return: {"status":"ok","uptime":12345,"port":37777}
   ```

2. **Check database for corruption**:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

3. **View stuck messages directly**:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "
     SELECT id, session_db_id, status, retry_count,
            (strftime('%s', 'now') * 1000 - started_processing_at_epoch) / 60000 as age_minutes
     FROM pending_messages
     WHERE status = 'processing'
     ORDER BY started_processing_at_epoch;
   "
   ```

4. **Force reset stuck messages** (nuclear option):
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "
     UPDATE pending_messages
     SET status = 'pending', started_processing_at_epoch = NULL
     WHERE status = 'processing';
   "
   ```

   Then trigger recovery:
   ```bash
   bun scripts/check-pending-queue.ts --process
   ```

5. **Check worker logs for SDK errors**:
   ```bash
   npm run worker:logs | grep -i error
   ```

#### Understanding the Queue Table

The `pending_messages` table tracks all messages with these key fields:

```sql
CREATE TABLE pending_messages (
  id INTEGER PRIMARY KEY,
  session_db_id INTEGER,          -- Foreign key to sdk_sessions
  claude_session_id TEXT,          -- Claude session ID
  message_type TEXT,               -- 'observation' | 'summarize'
  status TEXT,                     -- 'pending' | 'processing' | 'processed' | 'failed'
  retry_count INTEGER,             -- Current retry attempt (max: 3)
  created_at_epoch INTEGER,        -- When message was queued
  started_processing_at_epoch INTEGER,  -- When marked 'processing'
  completed_at_epoch INTEGER       -- When completed/failed
)
```

**Query examples**:

```bash
# Count messages by status
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT status, COUNT(*)
  FROM pending_messages
  GROUP BY status;
"

# Find sessions with pending work
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT session_db_id, COUNT(*) as pending_count
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  GROUP BY session_db_id;
"

# View recent failures
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, session_db_id, message_type, retry_count,
         datetime(completed_at_epoch/1000, 'unixepoch') as failed_at
  FROM pending_messages
  WHERE status = 'failed'
  ORDER BY completed_at_epoch DESC
  LIMIT 10;
"
```

## Hook Issues

### Hooks Not Firing

**Symptoms**: No context appears, observations not saved.

**Solutions**:

1. Verify hooks are configured:
   ```bash
   cat plugin/hooks/hooks.json
   ```

2. Test hooks manually:
   ```bash
   # Test context hook
   echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js
   ```

3. Check hook permissions:
   ```bash
   ls -la plugin/scripts/*.js
   ```

4. Verify hooks.json is valid JSON:
   ```bash
   cat plugin/hooks/hooks.json | jq .
   ```

### Context Not Appearing

**Symptoms**: No session context when Claude starts.

**Solutions**:

1. Check if summaries exist:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM session_summaries;"
   ```

2. View recent sessions:
   ```bash
   npm run test:context:verbose
   ```

3. Check database integrity:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

4. Manually test context hook:
   ```bash
   npm run test:context
   ```

### Hooks Timeout

**Symptoms**: Hook execution times out, errors in Claude Code.

**Solutions**:

1. Increase timeout in `plugin/hooks/hooks.json`:
   ```json
   {
     "timeout": 180  // Increase from 120
   }
   ```

2. Check worker is running (prevents timeout waiting for worker):
   ```bash
   npm run worker:status
   ```

3. Check database size (large database = slow queries):
   ```bash
   ls -lh ~/.claude-mem/claude-mem.db
   ```

4. Optimize database:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   ```

### Dependencies Not Installing

**Symptoms**: SessionStart hook fails with "module not found" errors.

**Solutions**:

1. Manually install dependencies:
   ```bash
   cd ~/.claude/plugins/marketplaces/thedotmack
   npm install
   ```

2. Check npm is available:
   ```bash
   which npm
   npm --version
   ```

3. Check package.json exists:
   ```bash
   ls -la ~/.claude/plugins/marketplaces/thedotmack/package.json
   ```

## Database Issues

### Database Locked

**Symptoms**: "database is locked" errors in logs.

**Solutions**:

1. Close all connections:
   ```bash
   npm run worker:stop
   ```

2. Check for stale locks:
   ```bash
   lsof ~/.claude-mem/claude-mem.db
   ```

3. Kill processes holding locks:
   ```bash
   kill -9 <PID>
   ```

4. Restart worker:
   ```bash
   npm run worker:start
   ```

### Database Corruption

**Symptoms**: Integrity check fails, weird errors.

**Solutions**:

1. Check database integrity:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

2. Backup database:
   ```bash
   cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
   ```

3. Try to repair:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   ```

4. Nuclear option - recreate database:
   ```bash
   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:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts';"
   ```

2. Rebuild FTS5 tables:
   ```bash
   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:
   ```bash
   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:
   ```bash
   ls -lh ~/.claude-mem/claude-mem.db
   ```

2. Vacuum database:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
   ```

3. Delete old sessions:
   ```bash
   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:
   ```bash
   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:
   ```bash
   cat plugin/.mcp.json
   ```

2. Verify search server is built:
   ```bash
   ls -l plugin/scripts/mcp-server.cjs
   ```

3. Rebuild if needed:
   ```bash
   npm run build
   ```

4. Restart Claude Code

### Search Returns No Results

**Symptoms**: Valid queries return empty results.

**Solutions**:

1. Check database has data:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   ```

2. Verify FTS5 tables populated:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"
   ```

3. Test simple query:
   ```bash
   # Test MCP search tool
   search(query="test", limit=5)
   ```

4. Check query syntax:
   ```bash
   # Bad: Special characters may cause issues
   search(query="[test]")

   # Good: Simple words
   search(query="test")
   ```

### Token Limit Errors

**Symptoms**: "exceeded token limit" errors from MCP.

**Solutions**:

1. Follow 3-layer workflow (don't skip to get_observations):
   ```bash
   # Start with search to get index
   search(query="...", limit=10)

   # Review IDs, then fetch only relevant ones
   get_observations(ids=[<2-3 relevant IDs>])
   ```

2. Reduce limit in search:
   ```bash
   search(query="...", limit=3)
   ```

3. Use filters to narrow results:
   ```bash
   search(query="...", type="decision", limit=5)
   ```

4. Paginate results:
   ```bash
   # First page
   search(query="...", limit=5, offset=0)

   # Second page
   search(query="...", limit=5, offset=5)
   ```

5. Batch IDs in get_observations:
   ```bash
   # Always batch multiple IDs in one call
   get_observations(ids=[123, 456, 789])

   # Don't make separate calls per ID
   ```

## Performance Issues

### Slow Context Injection

**Symptoms**: SessionStart hook takes too long.

**Solutions**:

1. Reduce context sessions:
   ```typescript
   // In src/hooks/context.ts
   const CONTEXT_SESSIONS = 5;  // Reduce from 10
   ```

2. Optimize database:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "
     ANALYZE;
     VACUUM;
   "
   ```

3. Add indexes (if missing):
   ```bash
   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.

**Solutions**:

1. Check current usage:
   ```bash
   npm run worker:status
   ```

2. Restart worker:
   ```bash
   npm run worker:restart
   ```

3. 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:
   ```bash
   /plugin marketplace add thedotmack/claude-mem
   ```

2. Then install:
   ```bash
   /plugin install claude-mem
   ```

3. Verify installation:
   ```bash
   ls -la ~/.claude/plugins/marketplaces/thedotmack/
   ```

### Build Failures

**Symptoms**: `npm run build` fails.

**Solutions**:

1. Clean and reinstall:
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

2. Check Node.js version:
   ```bash
   node --version  # Should be >= 18.0.0
   ```

3. Check for TypeScript errors:
   ```bash
   npx tsc --noEmit
   ```

### Missing Dependencies

**Symptoms**: "Cannot find module" errors.

**Solutions**:

1. Install dependencies:
   ```bash
   npm install
   ```

2. Check package.json:
   ```bash
   cat package.json
   ```

3. Verify node_modules exists:
   ```bash
   ls -la node_modules/
   ```

## Debugging

### Enable Verbose Logging

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

### Check Correlation IDs

Trace observations through the pipeline:

```bash
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

```bash
# Check if worker is running
npm run worker:status

# View logs
npm run worker:logs

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

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

### Database Inspection

```bash
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**:
   ```bash
   npm run worker:logs
   ```

2. **Create issue**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
   - Include error messages
   - Include relevant logs
   - Include steps to reproduce

3. **Check existing issues**: Someone may have already solved your problem

## Next Steps

- [Configuration](configuration) - Customize Claude-Mem
- [Development](development) - Build from source
- [Architecture](architecture/overview) - Understand the system