Skip to content

Troubleshooting

Jean-Baptiste THERY edited this page Jul 15, 2026 · 17 revisions

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 in parsed or embedded state without a committed index write are retried; files already in indexed state are not parsed or embedded again. 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.

If durable ingestion state is invalid or inconsistent with the current configuration, Ragmir ignores it and starts a new safe run. It does not resume from untrusted table names or staged manifest paths.

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.

Team members get different results

Confirm the shared source folder finished synchronizing, then compare the Ragmir version, configuration, embedding provider, model, and rgr sources list output. Missing, partial, or extra files create different local indexes. Run rgr ingest and rgr audit after synchronization; do not share an actively written .ragmir/storage/ directory.

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.

Clone this wiki locally