Repository navigation
Troubleshooting
Start with the smallest diagnostic:
rgr doctor
rgr doctor --deep
rgr audit --unsupported
rgr security-auditThe first command reads the last successful manifest health snapshot. Use --deep only when you
need a live O(corpus) inventory and executable security probes. rgr audit is also O(corpus).
Run rgr setup. It creates .ragmir/config.json, local ignore rules, and optional agent helpers.
Check sources with rgr sources list, then run rgr ingest. Use rgr audit to compare supported files with the index. Use rgr ingest --rebuild after changing embedding provider, model, or chunking.
Run rgr audit --json and read sourceRules. unmatchedExclusions lists exact !path rules that
name no file; check the spelling. excludedCopies lists excluded files whose identical copy is
still indexed under another path (an export folder, a backup): exclude that copy too. Versions
before 6.2 could miss accented names stored decomposed; rgr ingest applies the rules again.
rgr doctor warns when a Ragmir MCP server is registered for every project (Claude Code user
scope or ~/.codex/config.toml). Remove that registration and register the server per project, or
set mcpAllowedRoots in the base's config to refuse unrelated workspaces. Results already carry a
scope notice when the workspace is unrelated.
A server declared in .mcp.json only starts after approval. rgr doctor reports approval=pending
or approval=rejected; approve it when Claude Code asks, or add its name to
enabledMcpjsonServers in .claude/settings.local.json.
Run rgr storage gc --dry-run. storageDiskBytes counts old LanceDB versions and index files;
the next ingest prunes versions once more than 100 pile up, and rgr storage optimize prunes them
now. Orphans such as unused models (including chat models of retired Ragmir packages) and storage
copies are listed; rgr storage gc --orphans deletes them.
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. If source checksums or
the indexing policy changed, Ragmir starts a new safe run instead.
An interrupted rgr ingest --rebuild leaves the previous complete index active. Re-run the rebuild
to continue its isolated generation.
If the 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.
Antivirus scanners, search indexing, and sync clients such as OneDrive briefly hold new files on
Windows. Ragmir retries the atomic renames and directory removals they block for about two
seconds. If the error persists, keep .ragmir/ out of synced folders or exclude it from real-time
scanning, then run rgr ingest again; the active index stays searchable meanwhile.
If rgr doctor reports that the canonical activation manifest is missing or invalid, Ragmir uses
the last validated previous generation and keeps readiness false. Run rgr ingest --rebuild to
write a new canonical manifest. If both canonical and previous manifests are invalid, retrieval
does not fall back to an unverified default table.
rgr ingest --json reports emptyTextFiles. For scanned PDFs, run:
rgr ocr doctor
rgr ocr setup
rgr ingestOCR is local and opt-in. Generated PDF OCR runs in bounded page groups and resumes from private
content-addressed cache entries. The OCR metrics in rgr ingest --json and rgr preview --json
report cache hits, batches, subprocesses, and duration without page text. The full preview output
also includes extracted chunk text, so review it before sharing. Images and legacy .doc files
need explicitly configured local extractors.
Results marked weakEvidence hold few of the question's distinctive words and have no strong
semantic match: rephrase with the project's own terms or narrow the search with a scope. A
search returns nothing when its first five results are all weak; a rephrased question with the
project's vocabulary usually finds the evidence if it exists. When one
export or log dominates results, rgr audit reports index concentration; exclude it, lower it
with sourceWeights, or cap it with maxChunksPerDataFile.
First confirm source coverage with rgr audit. Then try a specific query, --context-radius 1, or a higher --top-k. For semantic retrieval, install optional @huggingface/transformers, then run rgr models pull --enable followed by rgr ingest --rebuild.
An error saying that Transformers.js loaded the model without its tokenizer, or the older
this.tokenizer is not a function, means the local model is not an offline snapshot. Earlier pulls
left a pinned revision in the Transformers.js cache layout, which offline loading cannot read.
Run rgr models pull --enable to install a complete snapshot of the pinned revision, then
rgr ingest --rebuild. The pull replaces the previous model only after the new snapshot is
complete and its digest is accepted.
Run rgr upgrade --check to see whether the active index predates the current schema or policy,
then run rgr upgrade. The new runtime refuses an incompatible index rather than returning unsafe
results, and the error points to this command. A required rebuild is written to an isolated
generation while the previous valid index remains untouched. Only a fully validated replacement
activates. If the process is interrupted, rerun the command to resume; do not delete
.ragmir/storage/ first. A long-running host can keep its already loaded runtime serving during the
rebuild, then restart or cut over once the upgrade reports status=current and ready=true. Use
rgr doctor --fix for current-config setup repairs. Retired configuration fields require
rgr upgrade first.
With configured external extractors (OCR or legacy Word commands), rgr upgrade and
rgr doctor --fix end with action=none: they never run those commands on their own. Run the
rgr ingest (or rgr ingest --rebuild) that their reason names.
advisory=... can accompany status=current: retrieval is compatible,
but a separate local security control still needs review. Run rgr security-audit for the exact
follow-up instead of deleting a healthy index.
Run rgr upgrade --check then rgr upgrade. It backs up retired masking/profile/logging settings
and stages the required index rebuild. Source text is now preserved. See migration.
rgr security-audit --strict exits with an error when warnings are present. Inspect the named file
permissions, Git exclusions, or external extractor. Warnings are separate from operational readiness.
OCR remains usable while its explicit external-process advisory is reported.
Compare source revisions, configured globs, package versions, model identity, and chunk settings.
Update sources through your normal Git workflow, then run rgr ingest on each machine. Use
rgr audit to check live coverage. Keep each actively written index local to its workstation.
Correct or remove the variable named in the error. Unknown JSON keys and invalid bounds are errors, so a typo never silently selects a different behavior.