AutoRAG Doctor

AutoRAG doctor

Goal: every configured datasource is indexed and actually returns hits. A green status is not enough — the run is done only when a real query returns a real hit per datasource, or the datasource is reported as genuinely empty or not configured.

Always finish with the status table in Report.

Safety

• Never delete, move, or edit source documents.
• Never delete a datasource's native store (~/Library/Application Support/katok, ~/.discrawl, ~/.mailcrawl, .qmd, Telegram/WhatsApp/Notion archives). AutoRAG only reads them; rebuilding them is the owning CLI's job.
• Only AutoRAG-owned state under AUTORAG_HOME and the workspace .autorag directory may be reset.
• Never print token or password values. Report credential names only.
• Kill a process only after confirming it is an AutoRAG-owned orphan.

1. Triage the core

autorag status --json
autorag health --json
autorag gateway status --format json

• status reports state, stale, diagnostics, and per-component state for minsync, jikji, and datasources. stale: true or any stale-index diagnostic means the corpus changed since the last successful refresh.
• health resolves the single search model and does one live completion probe. --skip-probes only proves config shape, never live access; do not claim a healthy model from it.
• The gateway is on-demand: stopped is normal when nothing is embedding. unavailable while a refresh is running is a real failure.

Config lives at --config, AUTORAG_CONFIG, $AUTORAG_HOME/config.json, or ~/.autorag/config.json. Read searchPaths, workspacePath, minSync, jikji, and datasources before changing anything.

If the CLI itself is missing or the config does not exist, stop and run the autorag-setup skill first — doctor repairs an existing install, it does not create one.

2. Probe every datasource natively

Each CLI owns its archive, so ask the CLI, not AutoRAG. A datasource is only active when its binary exists, its store is present, and its own check passes.

Rules:

• A missing binary is not configured, not a failure. Report it with the install command and move on.
• An empty store is a legitimate zero-hit result. telecrawl and slacrawl return JSON null (not []) for no hits — treat that as empty, not broken.
• A configured datasource whose native check fails is a failure and must be repaired or reported explicitly. Never report a skip as a pass.
• Zero hits with a non-empty store means the CLI's search path is suspect, not the data. Cross-check against the raw index before concluding (for example slacrawl sql "select count(*) from message_fts where message_fts match 'x';" against slacrawl search x). A populated index plus an empty CLI result is an upstream bug: report it with the exact reproduction instead of re-syncing.

3. Prove searchability

Indexing without retrieval is a failed run. Probe retrieval per datasource through the model-free MCP tools, then once end to end:

autorag.status {}
autorag.search {"query":"a word that certainly appears","topK":3}
autorag.search {"query":"recent topic","datasourceIds":["discord"],"topK":3}
autorag.search {"query":"recent mail subject","scope":"/mailcrawl/**","topK":3}

autorag search "summarize the collection" --top-k 3 --json --debug

• Always read the diagnostics returned by MCP autorag.search. A run that silently dropped a whole retrieval method still looks successful, just with fewer results; only the diagnostics name it (retrieval-method-failed). The model-backed CLI autorag search --json hides diagnostics, sessionId, and per-result evidence unless --debug is set, so pass --debug when diagnosing that path.
• A method missing from the returned method values means that method contributed nothing. During a full MinSync re-sync this is expected: the store is being rebuilt, minsync status reports NotSynced, and local-file hits stay absent until it finishes. Confirm with minsync status before treating it as a failure, and never kill a running sync to "fix" it.
• MCP autorag.search needs no model, so it isolates retrieval from model failures.
• Use MCP datasourceIds to select configured connections before retrieval; scope narrows results within scope-capable datasources. Discover connection IDs with autorag.datasources.list; descriptor tags are metadata only, not search filters. Every configured connection is searchable — if one returns nothing, investigate its native store, connector, or the query itself.
• autorag.evidence {"sessionId":"...","resultNumber":N} shows the exact chunk behind a numbered result; use it to confirm a hit is real and its source is readable. The CLI autorag evidence SESSION --json remains for terminal repair.
• Local-file hits must map to an absolute, existing path. Datasource hits keep source-native identities such as /kakao/personal/chunks/42; those are not filesystem paths and must never be passed to cat.

4. Repair playbook

Orphan lock

The embedding runtime keeps embedding-runtime.lock, embedding-runtime.pid, and embedding-runtime.port in AUTORAG_HOME. It reclaims them automatically when the recorded PID is dead; a lock-conflict means the PID is alive.

autorag gateway status --format json
autorag gateway stop

Only when gateway stop cannot clear it, and the recorded PID is confirmed dead (kill -0 PID fails), remove the three files by hand and retry.

Index locks are owned by their engines: MinSync/tantivy locks under <workspace>/.autorag/, and per-CLI locks such as <workspace>/.autorag/datasources/discrawl/.discrawl-sync.lock. Delete one only after confirming no owning process is alive; otherwise wait for the run that holds it.

Orphan process

pgrep -fl 'autorag|autorag-gateway|minsync' | grep -v pgrep

A refresh that was killed mid-run can leave the gateway or a minsync child alive. Stop the gateway with autorag gateway stop first; only kill a PID directly when it is confirmed orphaned (no parent CLI, no live refresh). Re-run autorag status --json afterwards to confirm inFlight: false.