Troubleshooting

Daemon won't start

cat ~/.recall/daemon.log | tail -50

Common causes:

• Port conflict — rare because we pick a free ephemeral port, but if something's broken, try recall stop && recall start
• SQLite lock — leftover .sqlite-wal / .sqlite-shm files. Safe to delete when the daemon is stopped

Browser opens but page is blank

• Check devtools console for errors
• recall stop && recall start to bounce the daemon
• Hard-refresh (Cmd+Shift+R / Ctrl+Shift+R)

Search returns nothing for a term I know exists

• Terms shorter than 2 chars are ignored (they produce garbage)
• FTS5 uses porter stemming — "running" matches "run" but quoted exact phrases don't stem
• Try reindexing: recall index --force

"Empty" assistant messages in older sessions

If you indexed before v0.4.0 and see lots of empty assistant messages, reindex:

recall index --force

The v0.4.0 parser captures tool calls as inline markdown — the old indexer dropped them.

Want to start completely fresh

recall stop
rm -rf ~/.recall
recall start
recall index

This wipes aliases, notes, pins, the database. Only do this if you want a truly clean slate — there's no undo.