> ## Documentation Index
> Fetch the complete documentation index at: https://rapidreview.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> The install, sign-in, and rate-limit failures people hit, and what to do.

Start with `nisa doctor` — it checks install, PATH, platform, backend, config, and which credential is in use, and prints fixes. `--json` for scripts.

| Symptom                                                                                                            | Cause                                                                                                                  | Fix                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `command not found: nisa`                                                                                          | `~/.local/bin` isn't on `PATH`                                                                                         | Add the `export PATH=…` line the installer printed to your shell profile                                        |
| The installer can't reach `api.rapidreview.io`                                                                     | Network policy                                                                                                         | Use the fallback installer URL or the archive — both under [Manual install](/docs/nisa/start/install#manual-install) |
| `nisa: not authenticated. Set RAPIDREVIEW_KEY, or run ./nisa (interactive) or ./nisa login in a terminal.`         | Headless run with no credential                                                                                        | `export RAPIDREVIEW_KEY=…` or sign in once in a terminal                                                        |
| `403 API key management requires browser login`                                                                    | `nisa keys …` while a key is the credential in use (`RAPIDREVIEW_KEY`, or the one the CLI's browser onboarding stored) | Manage keys in the web app (Settings → API Keys), or `nisa logout && nisa login` first                          |
| `rate limit: N chat calls in the last 60s (limit: 10). Wait ~Ns and retry.` (or `… in the last hour (limit: 100)`) | Chat-backed cap tripped                                                                                                | Wait; batch questions with `ask-batch`; use direct commands for lookups                                         |
| `search: too many queries (N); cap is 8`                                                                           | More than 8 `--query` values (4 for `semantic-search`)                                                                 | Split the call                                                                                                  |
| `excerpts` rejects `--format bibtex\|csv`                                                                          | Excerpts are JSON only                                                                                                 | Drop `--format`                                                                                                 |
| A recent paper is missing from `search`                                                                            | Ranking blends relevance with citations; or the index hasn't reached that month                                        | Check `index_latest_pub_month` in the response; try `semantic-search`; widen phrasings                          |
| More results requested than returned                                                                               | Server caps `--max-results` at 50 (`related --n` and `excerpts --max` clamp to 1–50)                                   | Paginate with `--offset` (itself clamped at 500; 200 for `semantic-search`)                                     |
| Exit `124`                                                                                                         | `--timeout` reached                                                                                                    | The partial answer is still in the JSON; the session is kept — `nisa exec --continue`                           |
| Login browser never opens                                                                                          | `--no-browser`, or no display                                                                                          | Open the printed URL yourself                                                                                   |

`nisa logout` deletes the local credentials file only — revoke keys with `nisa keys revoke <id>`. `nisa upgrade` re-runs the installer in place (`--check` exits `1` if a newer version exists).

Still stuck? Include the `nisa doctor --json` output when you ask.