# Troubleshooting

Diagnose a broken index with repowise doctor, then fix common problems such as command not found, indexing hangs, missing MCP tools and store drift.

## First, run `repowise doctor`

```bash
repowise doctor
repowise doctor --repair
```

[`doctor`](https://docs.repowise.dev/cli/other#repowise-doctor) validates the git repo, the `.repowise/` directory, the
SQLite + vector + FTS stores, the persisted provider config, and
checks for stale pages. `--repair` fixes most mismatches automatically.
For most issues, this is the only command you need to run.

## Common symptoms

### "command not found: repowise"

Your shell can't find the binary.

- If you used `pip install --user`: add `~/.local/bin` (Linux/macOS)
  or `%APPDATA%\Python\Scripts` (Windows) to `PATH`.
- If you used `uv tool install`: ensure `~/.local/bin` is on `PATH`.
- Verify with `which repowise` / `where repowise`.

### "ANTHROPIC_API_KEY is not set"

`repowise init` does not need one. Without a resolvable provider it
renders the wiki from your code's structure and exits 0, so a missing key
is never what stopped an `init` run. `update` in docs mode, `generate`,
`restyle`, and `health --generate-code` do need a provider. What a keyless
index gives you is on [Deterministic wiki](https://docs.repowise.dev/intelligence/deterministic-wiki),
and every key variable is on [Environment variables](https://docs.repowise.dev/installation/env-vars).

To set one:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
# Windows PowerShell:
$env:ANTHROPIC_API_KEY = "sk-ant-..."
```

To index with no model in the loop at all:

```bash
repowise init --yes --no-prose
```

### `REPOWISE_PROVIDER` is set but ignored

`REPOWISE_PROVIDER` and `REPOWISE_MODEL` apply only when no flag, no
`provider` / `model` in `.repowise/config.yaml` and no default saved from the
web UI settings names one. Choosing a model for a repo in the web UI writes
that repo's `config.yaml`, which then takes precedence. The full order is on
[Environment variables](https://docs.repowise.dev/installation/env-vars#provider-model-and-base-url-order).

An empty value is treated as unset, not as a provider named `""`. CI
matrices routinely export `REPOWISE_PROVIDER: ""` for the keyless arm, and
that resolves to normal auto-detection.

### Will an `init` prompt abort the run in CI?

No. If the first interactive prompt reads EOF, which is what happens when an
agent or a CI job pipes stdin, `init` prints a notice and continues with
defaults.

The cost gate behaves the same way: it never prompts when stdin is not a
terminal. It auto-declines, keeps the index it already built, and renders
the wiki from structure. `repowise init --yes` is the command to reach for
in a script.

### Indexing hangs or times out

- **Checked-in minified bundles** (webpack/rollup/storybook output and
  similar) pack thousands of near-identical tokens onto a few
  huge lines and can stall the duplication/health pass. repowise
  detects and skips minified/generated files automatically, but the
  cleanest fix is to keep them out of the index: they're already excluded
  if your `.gitignore` ignores them (repowise reads **nested `.gitignore`
  files**, so a per-package `.gitignore` in a monorepo works), or exclude
  explicitly with `repowise init -x '**/<build-output-dir>/**'`.
- **Tree-sitter crash on a generated file**: exclude with
  `repowise init -x 'src/generated/**'`.
- **Submodules being scanned unexpectedly**: they're skipped by
  default; only included with `--include-submodules`.
- **Network flakiness on LLM calls**: re-run `repowise init`; it's
  idempotent and resumes from the last checkpoint with `--resume`.

### Claude Code can't see the MCP tools

1. Confirm `.mcp.json` exists at the project root (`repowise init`
   writes it; [`repowise agents add`](https://docs.repowise.dev/cli/agents) wires an agent up
   again).
2. Confirm `~/.claude/settings.json` registers the server.
3. Restart Claude Code.
4. Run `repowise doctor`. It cross-checks both files.

If the agent uses `Grep` and `Read` instead of calling
[`get_overview`](https://docs.repowise.dev/mcp/get-overview), the server didn't connect.

In a directory with no `.repowise/`, the MCP server starts and every tool
answers with a "run `repowise init`" notice, writing nothing to disk. A plugin
install launches the server in every project the host opens, so that notice
means this project has no index yet.

### Wiki feels stale after a big merge

```bash
repowise update --since main
```

Or pass `--force` to `repowise init` to regenerate everything. After a
package upgrade, see [Upgrading](https://docs.repowise.dev/upgrading) first.

### Windows: codec errors during indexing

Set UTF-8 encoding before `init`:

```powershell
$env:PYTHONIOENCODING = "utf-8"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
repowise init
```

### Store drift (`SQL count` ≠ `vector count`)

```bash
repowise doctor --repair
# or, nuclear:
repowise reindex
```

`reindex` rebuilds the vector store from the wiki. Embedding-only,
no LLM cost.

### Hosted: indexing stuck on "queued"

Refresh the dashboard. If the status doesn't move within ~5 minutes
of submission, [contact us](mailto:hello@repowise.dev) and we'll check
the queue manually.

> **Note**
>
> Still stuck? Capture `repowise doctor` output and the last 50 lines
> of `.repowise/logs/repowise.log` and open an issue on
> [GitHub](https://github.com/repowise-dev/repowise/issues) or hop into
> [Discord](https://discord.gg/cQVpuDB6rh).