Repository navigation
Troubleshooting
Start with the smallest diagnostic:
rgr doctor
rgr audit --unsupported
rgr security-auditRun rgr setup. It creates .ragmir/config.json, local ignore rules, and optional agent helpers.
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.
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.
rgr ingest --json reports emptyTextFiles. For scanned PDFs:
rgr ocr doctor
rgr ocr setup
rgr ingestOCR is local and opt-in. Images and legacy .doc files require explicitly configured local extractors.
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.
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.
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.
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.