Troubleshooting

Troubleshooting

Start with the smallest diagnostic:

rgr doctor
rgr doctor --deep
rgr audit --unsupported
rgr security-audit

The first command reads the last successful manifest health snapshot. Use --deep only when a live O(corpus) inventory and executable security probes are needed. rgr audit is also O(corpus).

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 upgrade after a package update or when an incompatible indexing policy requires a safe rebuild.

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

For a Git-backed repository, start with rgr team sync --json. current and updated mean the fetched upstream and local index are aligned. Dirty, ahead, diverged, detached, and no-upstream states never modify the branch; follow the first recommended action through the normal Git or merge-request workflow. A fetch failure keeps the last valid index and marks upstream freshness as unverified. Use --no-pull when branch updates must remain manual.

If results still differ after Git is current, verify the same reviewed source contract and Ragmir version. Do not start with snapshots: use rgr team snapshot and rgr team compare only for exact diagnosis or a non-Git authority. Never share an actively written .ragmir/storage/ directory.

Search stops after updating Ragmir

Run rgr upgrade --check, then rgr upgrade. The new runtime refuses an incompatible index instead of reading an untrusted layout. A required replacement is built in an isolated generation and only activates after validation; the previous valid index is never deleted first. Rerun the command after an interruption to resume. For a long-running host, keep the already loaded runtime serving, then restart or cut over after the upgrade reports status=current and ready=true.

privacyCompliant=false and advisory=... can accompany status=current. Retrieval is compatible, but a separate local control needs review. Run rgr security-audit instead of deleting a healthy index.

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.