Troubleshooting — Rinari docs

Start here

In the app, the top bar shows the engine status. If the engine isn’t ready, that’s the first thing to look at.
In a terminal, rinari doctor inspects your installation without changing credentials or state, and rinari status shows the provider, model, profile, project and branch in use.

rinari doctor
rinari status
rinari version

You can also ask Rinari herself, from the CLI or the app: “why didn’t the last turn answer?” or “review session ses_…”. She reads the session and turn records (read-only) and points out known anomalies, such as a turn that never finished or an approval that was never resolved.

Installing and updating

Windows says the publisher is unknown

The installer isn’t code-signed yet, so Windows may show an unknown publisher warning or stop it with SmartScreen. Only run an installer you downloaded from the official Releases page. See Install on Windows.

0.2.x won’t open my data anymore

That’s expected after updating: the first time 0.3 opens, it migrates Rinari’s database, and 0.2.x refuses to open the new schema. Keep using 0.3 — your conversations, projects and providers are kept. See Install on Windows.

Update, repair or uninstall won’t start

They need Rinari Agent to be closed. Quit the app and try again.

Another rinari command is already on PATH

The installer found a different rinari earlier on your PATH — for example, a CLI installed from source with uv tool install. Whichever comes first wins. To see which one a terminal is using:

where.exe rinari

Remove or reorder the other entry if you want the installer’s rinari, or keep your own CLI and point it at the app with RINARI_AGENT_BIN (see CLI ↔ desktop).

Dictation

Rinari is not allowed to use the microphone — allow it in Windows’ microphone privacy settings.
The dictation model has not been downloaded — download one in Settings → Dictation.
Transcription took too long — pick a lighter model.

See Dictation.

`rinari desktop`

Message	What to do
`Desktop client not found.`	Install Rinari Agent, or set `RINARI_AGENT_BIN` to `rinari-agent.exe`.
`Desktop binary not found: …`	The path in `--binary` or `RINARI_AGENT_BIN` is wrong. Fix it; the command won’t fall back to another executable.
`Not a directory: …`	Pass a folder, not a file.

rinari agent runs a task in the terminal; it’s not the command that opens the app.

Providers and models

The test fails or authentication is rejected

With Environment variable, enter the variable’s name (OPENAI_API_KEY), not the key itself, and make sure the variable exists for the engine’s process.
For local servers, start Ollama or LM Studio first and check the endpoint.
From a terminal, rinari providers list shows the state of each provider, and rinari providers test <alias> tests one.

The model is listed but the turn fails

Discovering models only proves that the catalog is reachable. Generation, tool calling and vision need their own support: a model without tool calling can’t edit files or run commands. Pick a model that supports tools for BUILD work.

Projects

Local instructions, skills or plugins aren’t loading

The project isn’t trusted. Untrusted projects don’t load their instructions, skills, plugins, MCP servers or hooks. Trust the folder from the app, or in a terminal:

rinari trust status
rinari trust add

If its Git identity changed (a new remote or a re-created repository), trust needs to be revalidated: choose Trust again.

Resuming shows warnings

When a session resumes, the engine re-checks the project, branch, uncommitted changes, provider, trust and working directory, and reports differences as warnings instead of fixing them silently. Read them before continuing.

Logs, state and reporting a problem

Engine state lives in ~/.rinari, or in RINARI_HOME if set. Don’t move or replace it to reset Rinari: you would lose sessions and configuration.
Session traces: rinari logs tail, rinari trace.
Portable exports: rinari export session, rinari export config (secrets are never exported).

Settings → About → Export diagnostics saves a ZIP with the app and engine logs, crash dumps and a summary of versions, sizes and status — no messages, files or keys. Review it before sharing.

To report a bug, open an issue with your app and engine versions, the steps to reproduce it and the diagnostics ZIP or redacted logs. Never include provider keys or private project data.