---
title: "Troubleshooting"
description: "Common issues and solutions for claude-recall"
---
# 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_RECALL_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-recall-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-recall-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/nhevers
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/nhevers/.install-version
```
2. Force reinstall:
```bash
cd ~/.claude/plugins/marketplaces/nhevers
npm install --force
```
3. Check version marker:
```bash
cat ~/.claude/plugins/marketplaces/nhevers/.install-version
cat ~/.claude/plugins/marketplaces/nhevers/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_RECALL_WORKER_PORT=38000
npm run worker:restart
```
4. Verify new port:
```bash
cat ~/.claude-recall/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-recall/claude-recall.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-recall/claude-recall.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-recall/claude-recall.db "PRAGMA integrity_check;"
```
3. **View stuck messages directly**:
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall/claude-recall.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-recall/claude-recall.db "
SELECT status, COUNT(*)
FROM pending_messages
GROUP BY status;
"
# Find sessions with pending work
sqlite3 ~/.claude-recall/claude-recall.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-recall/claude-recall.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 extension/lifecycle/lifecycle.json
```
2. Test hooks manually:
```bash
# Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node extension/runtime/context-hook.js
```
3. Check hook permissions:
```bash
ls -la extension/runtime/*.js
```
4. Verify lifecycle.json is valid JSON:
```bash
cat extension/lifecycle/lifecycle.json | jq .
```
### Context Not Appearing
**Symptoms**: No session context when Claude starts.
**Solutions**:
1. Check if summaries exist:
```bash
sqlite3 ~/.claude-recall/claude-recall.db "SELECT COUNT(*) FROM session_summaries;"
```
2. View recent sessions:
```bash
npm run test:context:verbose
```
3. Check database integrity:
```bash
sqlite3 ~/.claude-recall/claude-recall.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 `extension/lifecycle/lifecycle.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-recall/claude-recall.db
```
4. Optimize database:
```bash
sqlite3 ~/.claude-recall/claude-recall.db "VACUUM;"
```
### Dependencies Not Installing
**Symptoms**: SessionStart hook fails with "module not found" errors.
**Solutions**:
1. Manually install dependencies:
```bash
cd ~/.claude/plugins/marketplaces/nhevers
npm install
```
2. Check npm is available:
```bash
which npm
npm --version
```
3. Check package.json exists:
```bash
ls -la ~/.claude/plugins/marketplaces/nhevers/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-recall/claude-recall.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-recall/claude-recall.db "PRAGMA integrity_check;"
```
2. Backup database:
```bash
cp ~/.claude-recall/claude-recall.db ~/.claude-recall/claude-recall.db.backup
```
3. Try to repair:
```bash
sqlite3 ~/.claude-recall/claude-recall.db "VACUUM;"
```
4. Nuclear option - recreate database:
```bash
rm ~/.claude-recall/claude-recall.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-recall/claude-recall.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts';"
```
2. Rebuild FTS5 tables:
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall/claude-recall.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-recall/claude-recall.db
```
2. Vacuum database:
```bash
sqlite3 ~/.claude-recall/claude-recall.db "VACUUM;"
```
3. Delete old sessions:
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall/claude-recall.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 extension/.mcp.json
```
2. Verify search server is built:
```bash
ls -l extension/runtime/search-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-recall/claude-recall.db "SELECT COUNT(*) FROM observations;"
```
2. Verify FTS5 tables populated:
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall/claude-recall.db "
ANALYZE;
VACUUM;
"
```
3. Add indexes (if missing):
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall` fails.
**Solutions**:
1. Add marketplace first:
```bash
/plugin marketplace add nhevers/claude-recall
```
2. Then install:
```bash
/plugin install claude-recall
```
3. Verify installation:
```bash
ls -la ~/.claude/plugins/marketplaces/nhevers/
```
### 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-recall:*
npm run worker:restart
npm run worker:logs
```
### Check Correlation IDs
Trace observations through the pipeline:
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall/worker.port
# Test worker health
curl http://localhost:37777/health
```
### Database Inspection
```bash
sqlite3 ~/.claude-recall/claude-recall.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-recall/` 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/nhevers/claude-recall/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-recall
- [Development](development) - Build from source
- [Architecture](architecture/overview) - Understand the system
