Troubleshooting

Troubleshooting

Start with the smallest diagnostic:

rgr doctor
rgr audit --unsupported
rgr security-audit

Project not initialized

Run rgr setup. It creates .ragmir/config.json, local ignore rules, and optional agent helpers.

Empty or stale index

Check rgr sources list, run rgr ingest, then use rgr audit to compare files with the index. Use rgr ingest --rebuild after changing the embedding provider, model, or chunking.

Scanned document has no text

rgr ingest --json reports emptyTextFiles. For scanned PDFs:

rgr ocr doctor
rgr ocr setup
rgr ingest

OCR is local and opt-in. Images and legacy .doc files require explicitly configured local extractors.

Weak search results

Confirm coverage with rgr audit. Try a more specific query, --context-radius 1, a higher --top-k, or --explain. For semantic retrieval, run rgr models pull --enable and then rebuild.

Strict audit fails

Run rgr security-audit --strict. It reports the exact local control that conflicts with strict mode, including ignored state, redaction, MCP bounds, and external extractors.

Chat or audio is not ready

Run rgr chat doctor or rgr audio --doctor. Normal offline use requires the optional public models to be present already.

Canonical source: docs/troubleshooting.md.