Skip to content
Troubleshooting
Run the doctor first. Most issues surface as a concrete suggestion.
$ recall doctor
▸ DB size: 912 MB
▸ WAL size: 167 MB (large)
▸ FTS5 fragmentation: low
▸ Free disk: 42 GB
▸ Integrity check: ok
⚠ WAL is 167 MB. Run recall optimize to truncate it.
Common scenarios
🐢
Feels slow
Run the doctor for concrete suggestions, then optimize if WAL or FTS5 is fragmented.
recall doctor
⚡
Daemon will not start
Tail the log. Common cause: leftover sqlite-wal/shm. Safe to delete when stopped.
tail -50 ~/.recall/daemon.log
⬜
Page is blank
Devtools console first. Then bounce the daemon, then hard-refresh.
recall stop && recall start
🔍
Search misses a known term
Terms shorter than 2 chars are dropped. FTS5 stems with porter; quoted phrases are exact. Try a forced reindex.
recall index --force
🪶
Empty assistant messages
Pre-v0.4.0 indexer dropped tool-call markdown. Reindex once.
recall index --force
🧹
Want a fully clean slate
Wipes aliases, notes, pins, the database. Only when you are sure.
recall stop && rm -rf ~/.recall && recall start

Troubleshooting

Hero above lists six common cases with fixes. One more:

#Maintenance

bash
recall optimize                           # safe while daemon is running
recall optimize --vacuum                  # full rewrite (requires recall stop first)

In order: WAL checkpoint → FTS5 segment merge → planner stats refresh → optional VACUUM. The daemon runs incremental versions on every clean shutdown, most users never need the manual command.

#Session titles are wrong

If sessions show the first user message instead of your VS Code / Cursor tab name, run recall doctor and read the Pipeline health section:

  • Auth rejections > 0: extension tried to sync but got 401. Reinstall the Marketplace extension, then "Developer: Restart Extension Host" from the palette.
  • Last ext sync = never (with daemon up more than 30s): extension isn't reaching the daemon at all. Check claude-recall.autoAlias is on.
  • Recent titles > 20% heuristic: pipeline degraded. Reinstall the extension, watch the rejection counter stop climbing.

Manual override anytime: recall name <id-prefix> "<actual name>" writes a permanent alias for any session, no extension required.

Last updated