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.

Ingestion was interrupted

Run rgr status --json, then start rgr ingest again. A compatible run resumes from its last committed file batch. Files already written to the index are not parsed or embedded again. Pending, failed, or changed files are retried. A different source inventory or indexing policy starts a new safe run.

An interrupted rgr ingest --rebuild leaves the previous complete index active. Run the rebuild again to continue its isolated generation. If one document keeps failing, the status output names the file and preserves progress for the healthy files.

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.