Skip to main content
Find the message you saw, apply the recovery, then run the verification shown with it.

​
Install ripgrep when rg is missing

Navi could not build its deterministic repository index. It can still ask the model, but it labels that answer ungrounded. Install ripgrep, then verify and repeat the original question:

​
Configure a missing API key

Navi selected a provider but could not find its key. Set the matching key and model, then repeat the command:
The Providers page lists the key names and Navi’s tested targets. Other models exposed by the installed Mastra router work when the selected model has the capabilities the command needs.

​
Match a rejected key to its provider

The selected provider/model and key variable do not match, or the key lacks access to that model. Set only the key for the gateway you chose.
Match the model’s provider prefix to that provider’s key. Do not use an OpenRouter model ID with a first-party key.

​
Select an available model ID

Model IDs are provider-qualified. Open the provider’s official model catalog from Providers, choose an available ID, then confirm the active value:

​
Remove incompatible DeepSeek-only settings

Navi reports either --thinking/--reasoning-effort are DeepSeek-only for a bare query or settings.thinking/reasoningEffort are DeepSeek-only for a flow. The command selected another provider while keeping DeepSeek-native settings. For a bare query, remove those flags or select a DeepSeek model. For a project-owned flow, either select DeepSeek or remove the static settings after inspecting the resolved plan:
Navi’s built-in flows do not require those static settings. DeepSeek’s managed model defaults still enable its native reasoning mode when you select a DeepSeek model. The install target already contains a file, directory, foreign symlink, or a skill managed by another installer. Navi will not overwrite it. Choose one owner:
  • For Navi’s zero-copy link and project-local launcher, remove the other installer’s files with that installer, then run npx --no-install navi-cli install.
  • For an npx skills managed copy, keep that copy and do not run npx --no-install navi-cli install at the same target.
Verify the target before retrying:
The Navi package directory moved after installation. Run uninstall, then install again from the new location:

​
Replace an unsupported in-memory NAVI_DB

Navi refuses in-memory SQLite URLs because its storage clients need one shared file. Use the default ledger, a file URL, or an ephemeral run:
The default is ~/.navi-home/navi.db.

​
Fix invalid input after exit 4

The CLI rejected its input before a valid result existed: a required argument was missing or the JSON input was invalid. Read the one-line error, then inspect the flow’s declared arguments:
JSON-typed inputs use --stdin; plain positional text cannot fill them. A malformed action.yaml or broken flow wiring exits 1, not 4. If the symptom is not here, run npx --no-install navi-cli --help and include the exact command, exit code, and stderr when reporting it.