Troubleshooting

command not found after install

Symptom: the installer finishes, but rift answers command not found in the same terminal.

Cause: a script cannot change the PATH of the shell that launched it. Editing a shell config only takes effect in terminals opened afterwards; the terminal the installer ran in has not reloaded it.

Fix: do what the installer prints. Either open a new terminal, or reload the file it names:

source ~/.zshrc

(Use the file it actually names: .bashrc, .profile, or similar.) If it linked into ~/.local/bin or another PATH directory instead, no reload is needed. Pass --no-modify-path only if you manage PATH yourself.

Installer 404 right after a release

Symptom: downloading rift-<os>-<arch>.zip or .tar.gz fails with 404, or the installer says it could not download the release.

Cause: the release is still publishing. The release workflow creates the GitHub release as a draft, uploads all twelve platform archives, checks every one is present, runs the install on Ubuntu, macOS and Windows, and only then marks the release public. A 404 mid-publish means an archive is not uploaded yet, or the release was pulled back to a draft after failed verification.

Fix: wait a few minutes and retry. Check which archives exist at https://github.com/Datum-Collective/RIFT-coding-agent/releases. If the version was pinned with --version, retry without the pin to take the latest public release.

opencode runs another program

Symptom: typing opencode starts something other than RIFT.

Cause: another tool installed its own opencode earlier on PATH.

Fix: use rift, which RIFT owns. The installer never overwrites: when it finds a command of the same name anywhere on PATH it prints Left opencode alone, <path> already exists and leaves it. rift uninstall only removes links that resolve to exactly its own binary, so the other program is never touched. Check with:

command -v rift
command -v opencode

A session is titled "New session"

Symptom: the session list shows New session - 2026-09-20T17:05:53.903Z (or Child session - ...) instead of a real title.

Cause: the model could not name the session. It errored, was rate limited, returned nothing, or no small model is configured. Titles matching that timestamp pattern are the built-in placeholder (isDefaultTitle in packages/opencode/src/session/session.ts).

Fix: rename the session with ctrl+r. If every session stays untitled, check the provider for the title model: rate limits, a missing small_model, or no auth. The fallback title builder (fallbackTitle in session/title.ts) names it from your own first words when the model fails.

The update prompt does not appear

Symptom: a newer release exists on GitHub but RIFT never asks.

Cause, in order of likelihood:

1. "autoupdate": false is set in config, which stops checking entirely (packages/opencode/src/cli/upgrade.ts).
2. The install method is not curl (for example a package manager copy). RIFT only self-updates curl installs.
3. The version was already handled: it was announced, installed, or skipped via skip this version in this run.
4. No network, or GitHub is unreachable. Failed checks are silent and retried at the next 30-minute tick.

Fix: check config first:

rift debug config

Remove or correct autoupdate, confirm the install method, and force the question with:

rift upgrade

Where logs are

• App log: opencode.log in the log directory. Run rift debug paths and look at the log line (for example /Users/shiv/.local/share/opencode/log).
• Global paths (data, config, cache, state): rift debug paths.
• Both version numbers in one place: rift debug info (RIFT release plus OpenCode runtime).
• Config the app actually loaded: rift debug config.
• Uninstall preview: rift uninstall --dry-run shows what would be removed without removing.