TroubleshootingTroubleshooting

Run Doctor first

rightnow doctor

• --json prints the report as JSON. Doctor checks the configured endpoint without sending a request and exits 0 even when it lists issues.
• Doctor does not validate provider credentials or executable lookup on PATH. Terminal, keyboard, color, and clipboard findings: Terminal Support guide.
• Logs: ~/.rightnow/logs/unified.jsonl by default. RIGHTNOW_HOME relocates the product home, and a preserved legacy home may also be selected. rightnow --debug adds per-session logs under <RIGHTNOW_HOME>/debug/.

RIGHTNOW_API_KEY is missing

$ rightnow -p "say hello"Copy
RightNow needs an API key for provider `runinfra`. Please set one of the configured environment variables (RIGHTNOW_API_KEY, RUNINFRA_GATEWAY_KEY), or update api_key/env_key in <config-path>, or run `rightnow auth login --provider runinfra`, or use /connect in RightNow.
Error: RightNow needs an API key for provider `runinfra`. Please set one of the configured environment variables (RIGHTNOW_API_KEY, RUNINFRA_GATEWAY_KEY), or update api_key/env_key in <config-path>, or run `rightnow auth login --provider runinfra`, or use /connect in RightNow.

Shown for the RunInfra preset, which configures both variable names; the config path varies, and a single name uses singular wording.

Fix: connect a provider, or save a RunInfra key:

rightnow auth login --provider runinfra

Or set it for the current PowerShell session, replacing <your key>:

$env:RIGHTNOW_API_KEY = "<your key>"

On macOS and Linux, use export RIGHTNOW_API_KEY='<your key>'. The shipped config stores env_key = "RIGHTNOW_API_KEY", not the credential value.

Connection failure

Shown in an interactive session when a prompt cannot reach the provider.

$ rightnowCopy
Connection failed — error sending request. Check your network and try again.

Fix: check the network and send the prompt again. If it persists, review the provider and endpoint settings.

Unknown model

$ rightnow -p "say hello" --model runinfra-qwen3-8-flash-nextCopy
Error: --model expects provider/model (e.g. runinfra/qwen3-8-flash-next), got "runinfra-qwen3-8-flash-next".

Fix: Use a model listed by rightnow models, or use the provider/model form for a model outside the catalog.

rightnow models

Authentication or connection failure

rightnow auth status

• Shows the active provider, model, and credential source; --json emits one JSON object.
• rightnow auth logout runinfra removes the stored RunInfra key; /connect replaces a key in a session. A provider environment variable stays active after logout.
• Confirm that the active config contains the RunInfra provider and model entries, including the /v1 suffix on https://api.runinfra.ai/v1.
• Headless backend unavailability returns exit code 23. A malformed config or startup failure outside the headless outcome mapping returns 1.

Installation or PATH failure

Native binaries are available for Windows x64, Windows ARM64, macOS Apple Silicon, macOS Intel, Linux x64, Linux ARM64. Linux binaries are static and do not require glibc.

Windows 10 or 11: 64-bit Windows PowerShell 5.1 or PowerShell 7

macOS and Linux: bash 3.2 or newer with curl or GNU wget

Git Bash delegates to PowerShell. WSL uses the Linux binary.

rightnow is not found

• Windows: the installer prepends the selected bin directory to the user PATH only when it is absent; open a new terminal.
• macOS and Linux: the installer uses the selected bin directory if it is on PATH, else links rightnow into a writable, safe ~/.local/bin, ~/bin, or /usr/local/bin already on PATH, else writes a marked, installer-owned PATH block for the active shell.
• For Bash, the block goes into ~/.bashrc and also an existing ~/.bash_profile; on macOS without that file, it uses an existing ~/.bash_login or ~/.profile, or creates ~/.bash_profile when neither exists. zsh uses ${ZDOTDIR:-$HOME}/.zshrc and fish ${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish. Only when no shell file can be selected does the installer print a manual PATH instruction.
• Open a new terminal or source the file named by the installer, then run command -v rightnow. If lookup still fails, inspect the # >>> rightnow installer PATH >>> block.

Download or checksum failure

• If the installer cannot fetch the manifest or reports a SHA-256 mismatch, stop and retry when the hosted release is available. Do not bypass checksum verification. Missing platform metadata means that platform is unavailable; never substitute another artifact or guess a URL.
• The Unix installer also needs sha256sum or shasum; BusyBox wget is not supported. Behind a proxy or private CA, set HTTPS_PROXY and NO_PROXY, and point RIGHTNOW_EXTRA_CA_BUNDLE at a PEM bundle; ~/.curlrc and ~/.wgetrc are ignored.
• Windows checks the native binary's SHA-256 against the sidecar and manifest and checks the manifest size. On Unix, SHA-256 is always checked against the sidecar. With Python 3 or jq, the Unix installer also validates the manifest metadata, its artifact hash, and recorded size. Without either parser, it reports sidecar-only verification.
• Both installers prove --version, retain the previous binary for rollback, and write installer.toml. They do not write config.toml. Completion generation is best effort: a failure only warns.

Locations and updates

• When no home or bin override or preserved legacy home applies, Windows installs to %USERPROFILE%\.rightnow\bin, and macOS and Linux install to ~/.rightnow/bin. When ~/.rightnow is absent and ~/.grok/config.toml exists, the installers retain ~/.grok as the product home.
• RIGHTNOW_HOME (legacy GROK_HOME) and RIGHTNOW_BIN_DIR override the locations; RIGHTNOW_BIN_DIR, RIGHTNOW_VERSION, and RIGHTNOW_CHANNEL win over their legacy aliases.
• rightnow update installs from the selected stable or alpha channel; rightnow update --check --json previews the decision. Details: Install.

Windows-specific behavior

• File-path completion returns no suggestions on Windows by design; it is not an installation failure.
• The dated record reports a quoting defect in the shared cmd /C path used by external auth-provider commands: avoid embedded double quotes there until it is requalified.
• Sandbox profiles are accepted but not enforced on Windows.

Build from source

The agent source is not published. Enterprise customers can ask us about source access. With a source checkout:

Config sync reports a warning

• A current version with missing template keys is left untouched. Compare it with config/rightnow.toml and add required keys deliberately.
• A user version newer than the template is left untouched.
• A concurrent modification aborts replacement and leaves the timestamped backup.
• Removed local-runtime keys are ignored and reported as unknown fields. Back up the config before removing them.

Windows PowerShell, default product home:

rightnow config sync --config "$HOME\.rightnow\config.toml" --template ".\config\rightnow.toml"

macOS and Linux:

rightnow config sync --config "$HOME/.rightnow/config.toml" --template "./config/rightnow.toml"

Source changes seem ignored

A running warm agent service keeps serving after a same-version or unversioned development rebuild. Check it with rightnow leader status, stop it, rebuild, and start a new invocation (daemon is an alias for leader).

rightnow leader stop

protoc is missing

Do not install protoc solely for this repository. The build checks PROTOC, the repository wrapper, and PATH, then falls back to the vendored executable. If PROTOC is set explicitly, verify that the file exists and answers --version.

The system prompt is unexpected

The source launchers never pass --system-prompt-override, so inspect the active config and direct CLI flags. A fresh session appends --rules inside <human_rules>. A resumed session keeps its original rules unless an effective override applies; then it uses that override with the currently supplied rules.

Related

• Install
• Authentication
• Terminal Support
• Headless Mode
• Known Issues