Troubleshooting

First, run repowise doctor#

repowise doctor
repowise doctor --repair

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, and every key variable is on Environment variables.

To set one:

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

To index with no model in the loop at all:

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.

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 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, 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#

repowise update --since main

Or pass --force to repowise init to regenerate everything. After a package upgrade, see Upgrading first.

Windows: codec errors during indexing#

Set UTF-8 encoding before init:

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

Store drift (SQL count ≠ vector count)#

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 and we'll check the queue manually.