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"

init and update need an LLM provider unless you pass --index-only.

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

To skip the LLM entirely:

repowise init --index-only

Indexing hangs or times out

• 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.

Claude Code can't see the MCP tools

1. Confirm .mcp.json exists at the project root (repowise init writes it).
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.

Wiki feels stale after a big merge

repowise update --since main

Or pass --force to repowise init to regenerate everything.

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