---
title: "Troubleshooting"
image: "https://recall.edheltzel.codes/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://recall.edheltzel.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

New install? The first-run walkthrough is [Getting Started](https://recall.edheltzel.codes/docs/).

## First Step: Run Doctor

```bash
recall doctor
```

This checks all subsystems: database, MCP registration, hooks, extraction tracker, CLI paths, and Ollama. **Start here before debugging individual issues.**

## Common Issues

### "Database not found"

```bash
recall init
```

Re-initializes the database. Safe to re-run — won't destroy existing data.

### "L0 identity tier is empty at session start"

The `RecallStart` hook loads `identity.md` for the L0 tier. If you've never
written one, the L0 section of your session-start context is empty.

```bash
recall onboard                 # Interactive interview — creates identity.md
recall benchmark run B         # Confirm v2_l0_chars > 0 after onboarding
```

If onboard writes to the wrong location, check for `RECALL_IDENTITY_PATH` in
your shell env, a project-local `./.atlas-recall/identity.md`, or an existing
user-owned `~/.claude/MEMORY/identity.md`. See
[Identity & Onboarding](https://recall.edheltzel.codes/docs/reference/cli/#identity--onboarding) for the complete
shared precedence.

### "My identity.md was silently truncated"

`RecallStart` hard-caps L0 at `MAX_L0_CHARS = 1200` on read and appends
`[identity truncated — edit <path> to shorten]`. Trim your identity file or
re-run `recall onboard --print` to preview length before writing.

### "Bun install fails — unzip required" (Linux only)

```bash
sudo apt-get install -y unzip
```

Then re-run `./packaging/install.sh`.

### "Fabric extraction failed"

Fabric is the `fabric` Extractor for Curated LoA. `recall loa write` requires it and fails closed if Fabric is missing. `recall dump` tries Fabric and, on failure, writes a basic summary (not a second Extractor). Core search, add, and MCP tools work without Fabric.

Verify Fabric works:

```bash
echo "test" | fabric --pattern extract_wisdom
```

### "MCP server not connecting"

1. Run diagnostics: `recall doctor`
2. Check config: `grep recall-memory ~/.claude/settings.json`
3. Verify PATH: `which recall-mcp`
4. Test manually: `recall-mcp` (should hang waiting for stdin — Ctrl+C to exit)
5. Restart Claude Code

The MCP server is registered in `~/.claude/settings.json` under `mcpServers` (user scope).

### "MCP worked yesterday but broke after I restarted Claude Code"

The installer-managed Claude MCP entry runs `bun` with args `run` and the `recall-mcp` path (`which recall-mcp`, usually `~/.bun/bin/recall-mcp`). That symlink points at this checkout's `dist/mcp-server.js`. If the symlink is gone or stale, the running `recall-mcp` process keeps the deleted inode open — so the current session works, but the next Claude Code restart can't spawn a fresh MCP server and it silently fails.

Common causes:
- `bun unlink`, `bun upgrade`, or `npm` clean-up removed the symlink
- An older `./packaging/update.sh` (pre-0.7.21) didn't re-run `bun link` after
  rebuild, leaving the symlink stale after `bun install` pruning
- `./packaging/update.sh` was run from a git worktree instead of the main
  checkout, redirecting the global `recall` registry to the worktree
  — which then vanished when the worktree was removed

**Repair:**

```bash
cd /path/to/Recall       # the MAIN checkout, not a worktree
bun install && bun run build && bun link
ls -la ~/.bun/bin/recall ~/.bun/bin/recall-mcp    # verify symlinks exist
# Restart Claude Code
```

Or, from a shell:

```bash
cd /path/to/Recall
./packaging/update.sh --force --no-confirm
```

Starting in **0.7.21**, `./packaging/update.sh` runs `bun link` after every
rebuild. Starting in **0.7.22**, it also *verifies* that the bin
symlinks resolve to readable files after linking — so a silent
`bun link` no-op now surfaces with a diagnostic instead of reporting
"[OK] Re-linked" while the bin dir stayed stale.

### "Session extraction not running"

1. Run diagnostics: `recall doctor`
2. Check hook registered: `grep RecallExtract ~/.claude/settings.json`
3. Check hook file exists: `ls ~/.claude/hooks/RecallExtract.ts`
4. Check bun accessible: `which bun` (hooks resolve bun dynamically — not hardcoded)
5. Check claude CLI available: `which claude`

Extraction hooks fire on the `Stop` event. If the hook isn't registered in `settings.json`, re-run `./packaging/install.sh`.

### "OpenCode sessions are not being captured"

1. Verify the host and runtime: `opencode --version` and `bun --version`.
2. Verify the host export contract: `opencode export <session-id>` should print JSON.
3. Check the installed plugin, its helper, and the config: `ls ~/.config/opencode/plugins/RecallExtract.ts ~/.config/opencode/plugins/lib/session-export.ts` and inspect `opencode.json` for `mcp.recall-memory`. The plugin imports the helper, so an install that predates it fails to load and captures nothing. Re-run `./packaging/install.sh` (or `./packaging/update.sh`) to place both.
4. Check the drop directory: `ls ~/.agents/Recall/MEMORY/opencode-sessions/`.
5. Run the batch extractor manually with `bun run ~/.agents/Recall/shared/hooks/RecallBatchExtract.ts --dry-run`.

The plugin tracks a session only after a successful JSON export and markdown
write. Export failures are reported to stderr and retried on a later idle event;
they do not silently become successful extraction records.

### "Search returns nothing, but the data is there"

`recall show` / `recall recent` find records that `recall search` never
returns. The usual cause is an FTS5 index out of sync with its source table —
classically a database created by an older version where the index or its
sync triggers were never created, so every write since has been silently
unindexed.

```bash
recall doctor            # the FTS index check reports which indexes drifted
recall repair            # dry-run: shows the planned rebuilds, writes nothing
recall export --backup   # recommended before any repair
recall repair --execute  # rebuild the indexes from the source tables
```

See [Repair in the CLI reference](https://recall.edheltzel.codes/docs/reference/cli/#repair) for the full
safety model. `recall doctor --fix` does **not** fix this. Doctor repairs
install and Claude MCP configuration drift; data and index maintenance always
goes through `recall repair`.

### "Embedding service unavailable"

Embeddings are optional. Hybrid search falls back to FTS5-only automatically.

To enable semantic search:

```bash
ollama pull qwen3-embedding:0.6b
curl http://localhost:11434/api/tags   # Verify Ollama is running
```

Set `OLLAMA_URL` environment variable if Ollama runs on a different host (default: `http://localhost:11434`).

### "Command not found: recall"

The `recall` CLI is linked globally via `bun link`, producing a symlink
at `~/.bun/bin/recall` → the Recall checkout's `dist/index.js`. If that
symlink is missing or stale:

```bash
cd /path/to/Recall       # the MAIN checkout, not a worktree
bun install && bun run build && bun link
ls -la ~/.bun/bin/recall    # verify
recall --version            # full X.Y.Z
```

If `recall --version` still fails, confirm `~/.bun/bin` is on your PATH:

```bash
echo $PATH | tr ':' '\n' | grep bun
```

Add to your shell init if missing:

```bash
# fish
set -U fish_user_paths $HOME/.bun/bin $fish_user_paths

# bash/zsh
export PATH="$HOME/.bun/bin:$PATH"
```

**Recovery via update.sh** (0.7.22+ verifies the symlink
post-rebuild and fails loudly if linking silently no-ops):

```bash
cd /path/to/Recall
./packaging/update.sh --force --no-confirm
```

See also: ["MCP worked yesterday but broke after I restarted Claude Code"](#mcp-worked-yesterday-but-broke-after-i-restarted-claude-code)
for the `recall-mcp` counterpart — same root cause, same repair path.

Source: https://recall.edheltzel.codes/docs/troubleshooting/index.mdx