Troubleshooting
Start with rift doctor. It names what is wrong and gives 1 action. This page lists every state it can report and every line rift status prints.
Start here#
rift doctorRift is working. Nothing needs attention.If the shell answers command not found: rift, the command is not on your PATH. A package install puts it at ~/.rift/bin/rift. Use that full path, or add the folder to your PATH.
rift doctor only reads. It exits with code 1 when something is broken. To hand the problem to an agent, run rift doctor --copy-prompt. It builds a prompt with private details removed and copies it.
The engine does not answer#
| What you see | Cause | Do this |
|---|---|---|
| "Rift is not set up on this Mac yet" | No config file | rift onboard |
| "Rift has no access token on this Mac" | No token in the Keychain | rift token issue |
| "Rift's daemon rejected this command's token" | The token is out of date | rift token issue |
| "Rift's background engine is not responding" | The engine is not running | launchctl kickstart -k gui/$UID/com.getrift.daemon |
| "Login Keychain is locked" | Common over SSH | security unlock-keychain ~/Library/Keychains/login.keychain-db |
| The installer says port 3577 is in use | Another program holds the port | Stop that program, then run the installer again |
Engine logs are in ~/Library/Logs/Rift/ on a package install.
What doctor can report#
Doctor checks these in order and leads with the first one that is broken. Errors from before the engine last started are ignored.
| State | Level | Means | Do this |
|---|---|---|---|
voyage_key_missing | Broken | Capture is on and there is no embedding key | Turn Search by meaning on in the app's Privacy settings, or rift onboard --reconfigure-voyage |
semantic_search_off | Warning | No embedding key. Keyword search works | The same, if you want search by meaning |
codex_auth_expired | Broken | Codex is signed out | codex login |
codex_preflight_failed | Broken | Codex could not run. See the table below | Depends on the cause |
claude_auth_expired | Broken | Claude Code is signed out | Run claude and sign in |
claude_preflight_failed | Broken | Claude Code could not run. See the table below | Depends on the cause |
voyage_embed_errors | Broken | An embedding request failed | rift status, then rift onboard --reconfigure-voyage if it names the key |
index_write_errors | Broken | A write to the index failed | rift status, then rift reindex |
capture_failed | Broken | The last Capture run had errors | Nothing. Onadit retries |
capture_daemon_stale | Warning | A scheduled run failed, but a later manual run worked | Nothing |
inbox_import_errors | Warning | An export dropped in the inbox could not be read | Export again and drop the new file |
mcp_not_installed | Warning | A tool on this Mac is not connected | rift mcp install --client=<name> |
menu_bar_unavailable | Warning | SwiftBar is not installed | Install SwiftBar, then rift menubar install |
menu_bar_broken | Warning | The menu-bar plugin is damaged | rift menubar install |
capture_quarantined | Warning | Some sessions were too large and ran out of retries | rift doctor repair capture-large-sessions |
capture_repairing | Warning | Large sessions are being saved in the background | Nothing |
update_available | Warning | A newer version is out | See Update |
When Capture cannot use Codex#
Capture runs a short check before each run. If it fails, rift status shows why.
| Cause | Message | Do this |
|---|---|---|
auth | "Codex login appears to have expired." | codex login |
model | "Codex rejected the model …" | Set codex_cli.model in the config to a model your plan offers |
cli_incompatible | "Codex CLI is too old for capture" | Upgrade Codex |
binary | "Codex CLI could not be found or started" | Check that it is installed and on the PATH |
rate_limit | "Codex hit a rate/usage limit or is out of credits" | Wait, or check your plan |
timeout, backend, unknown | A timeout or a network problem | Nothing. Onadit retries |
These are problems with the Codex install or its sign-in. Onadit does not hold a Codex or OpenAI key.
When Capture cannot use Claude Code#
| Cause | Do this |
|---|---|
missing | Install Claude Code, or set RIFT_CLAUDE_CLI_PATH |
incompatible | Upgrade Claude Code |
wrapper | A wrapper script is in the way. Set RIFT_CLAUDE_CLI_PATH to the real binary |
auth | Run claude and sign in |
rate_limit | Wait |
network | Check your connection |
timeout, unknown | Nothing. Onadit retries |
What rift status prints#
| Line | What it tells you |
|---|---|
| Header | The version, whether the engine is running and for how long, and the port. A cross after the port means Capture is on with no embedding key |
Voyage: | The embedding key is valid, and when it was last used. Replaced by Search: when there is no key |
Search: | keyword on · semantic off when there is no key |
Index: | When the index was last written, and the last error if there was one |
Inbox: | Whether an export was dropped in data/inbox/, and how many are pending |
Memory: | How many conversations, digests and documents Onadit holds, and why a count is 0 |
Codex CLI: or Claude Code: | Whether the tool Capture uses is signed in and working |
Capture: | The last run: how many sessions were saved, sent to review, or failed, and when the next run is due |
Cursor:, Cowork:, Grok CLI: | Whether each opt-in source is on, and how to turn it on |
App chats: | Chat apps found on this Mac whose chats need an export |
MCP: | Which tools are connected. A cross comes with the command that fixes it |
Menu bar: | Only shown when the menu-bar item is missing or broken |
Update: | Only shown when a newer version is out |
Next: | 1 action, or "nothing broken" |
The reasons a Memory: count can be 0: for digests, AI enrichment off or none yet. For documents, no sources, source missing, source empty or Voyage key missing.
Other messages#
| Message | Do this |
|---|---|
| "Authentication failed. Run: rift token issue" | Run it |
| "Cannot connect to daemon" | Restart the engine with the launchctl kickstart command above |
| "Config not found" | rift onboard, or point RIFT_CONFIG at the file |
| "Config invalid" | Fix the key it names. Unknown keys are rejected |
| "has keys this CLI does not recognize" | The config was written by a newer version. Update Onadit |
| "Rate limited. Retry later." | Wait a minute |
| "Another exclusive operation is running" | A rebuild or reindex is in progress. Wait for it |
Common fixes#
- The menu-bar icon is missing: open SwiftBar, then run
rift menubar install. - The Claude Code hook gets in the way: set
RIFT_POLICY_DISABLED=1, or remove therift-policy.mjsentry from~/.claude/settings.json. - Search by meaning stopped working:
rift onboard --reconfigure-voyagereplaces the key. - An agent does not use Onadit: check the
MCP:line inrift status, then add the line to your rule file.
Last updated 12 October 2026. This page is also available as Markdown, and every page is listed in llms.txt.