> For the complete documentation index, see [llms.txt](https://docs.loci-dev.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loci-dev.net/loci-plugin-for-ai-coding-assistants/loci-claude-plugin/troubleshooting.md).

# Troubleshooting

### `loci` CLI not found

1. Check it's on PATH: `command -v loci` and `loci --version`.
2. If missing, the background install may still be running or may have failed. Run `/loci:setup` to reinstall and verify — it's safe to re-run.
3. Confirm `uv` is installed (`command -v uv`) — the plugin needs it to install the CLI.
4. If the install itself failed, check `~/.loci/state/loci-cli-install.log` for the cause (commonly: `uv` can't reach PyPI, or an old `uv` version).

### A skill reports `auth_required`

Every analysis skill needs a signed-in session (see Authenticating).

1. Run `! loci login`, then retry.
2. Confirm with `! loci auth status` that it shows `signed_in`.

### A skill reports `quota_exceeded`

You're signed in, but you've hit your plan's daily limit. The error message includes the reset time and an upgrade link — this is not a bug, and retrying won't help until the window resets.

### Auto-skills didn't fire

* `loci-preflight` only runs in `/plan` mode — confirm you're describing new logic, not just asking a question.
* `loci-post-edit` only runs after edits to C/C++/Rust source files (`.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hpp`, `.hxx`, `.rs`).
* Both compile the source themselves — they need a supported LOCI target and a working cross-compiler for it on PATH, plus a valid session context from startup. If the compiler is missing, install it (or point LOCI at it) and re-run.

### On-demand skills didn't respond

* Type `/help` to confirm LOCI is loaded and see the full skill list plus your environment status.
* Restart Claude Code from inside your project directory if the build environment wasn't detected at session start.
* Check that a cross-compiler is installed and on PATH for your target — see the Installing prerequisites table.

### Environment health check

```
! loci doctor
```

Runs 10 checks (Python version, analysis-stack imports, `c++filt`, credential store, sign-in, state directory) and reports `data.healthy: true/false` plus per-check detail. Works signed out.

### Nothing seems to work

Run `/bug-report` and describe what you expected vs. what happened. It generates a full diagnostic report — environment snapshot, a 10-point checklist, and root-cause reasoning — as a timestamped `.md` file you can share with support or load into a new Claude Code session for further investigation. It works even when LOCI is completely broken (it avoids calling any of the analysis commands that might be the thing that's failing).