Skip to content

Troubleshooting ​

When search returns nothing, a datasource disappears from results, refresh hangs, or the embedder is unavailable, work through this page. It covers the first triage commands, per-datasource native checks, every diagnostic code AutoRAG emits, and the repair playbook.

Indexing is not searchability. A green status proves the corpus was indexed, not that a source actually returns hits. Always confirm retrieval with a real query before calling a source healthy.

Start with the doctor skill ​

Run the autorag-doctor agent skill: point your coding agent at skills/autorag-doctor/SKILL.md and say "check AutoRAG". It walks the full diagnose-and-repair procedure — core triage, per-datasource native probes, searchability proofs, repairs — and ends with the per-datasource status table below. Use it for anything beyond the quick checks on this page.

First triage ​

bash
autorag status --json          # freshness, per-component state, diagnostics
autorag health --json          # model resolution + one live completion probe
autorag setup --format json    # resolves the embedding backend and reports it
  • 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 proves config shape only — never claim a healthy model from it.
  • setup --format json reports embedding.backend (remote, daemon, or in-process) with the resolved provider/model/dimension, or embedding.reason plus a remediation when none is alive. It only probes; it never starts a daemon.

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

Then prove searchability through the model-free MCP server, which isolates retrieval from model failures:

text
autorag.status {}
autorag.search {"query":"a word that certainly appears","topK":3}
autorag.search {"query":"recent topic","datasourceIds":["discord"],"topK":3}

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 path hides diagnostics, sessionId, and per-result evidence unless --debug is set:

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

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. Inspect the exact chunk behind a numbered result with autorag evidence <session> --json (or MCP autorag.evidence).

Per-datasource status ​

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

DatasourceNative checkRe-sync when empty or stale
MinSync (local docs)minsync status, minsync check, minsync verifyautorag refresh --method minsync
Jikji (discovery)jikji doctorautorag refresh --method jikji
Everything (Windows file names)autorag status --json → components.everythingautorag refresh --method everything --json
KakaoTalklazykatok doctorlazykatok sync && lazykatok index
Discorddiscrawl --json metadatadiscrawl sync
Slackslacrawl --json doctorslacrawl sync
WhatsAppwacrawl --json doctorwacrawl import
Telegramtelecrawl --json doctor, telecrawl --json statustelecrawl import
Notionnotcrawl doctor, notcrawl statusnotcrawl sync --source desktop
Obsidian / notesautorag status (AutoRAG-owned index)autorag refresh --method datasources; if corrupt, delete .autorag/datasources/obsidian/<instance> first
Mailmailcrawl doctor, mailcrawl statusmailcrawl sync && mailcrawl index
Coding-agent sessionswombat doctor --jsonwombat sync --index
Lark / Feishulark-cli auth status --format jsonno local sync; search is remote

Rules:

  • A missing binary is not configured, not a failure. Report it with its 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; a populated index plus an empty CLI result is an upstream bug — report it with the exact reproduction instead of re-syncing.

Native stores stay owned by their CLIs — AutoRAG never rebuilds them. Fix a broken archive with the owning CLI's doctor, then autorag refresh --method datasources --json.

Diagnostic codes ​

CodeMeaningFirst move
stale-indexSources changed since last refreshautorag refresh --method parsed,minsync --json
index-not-readyIndex missing or never builtautorag refresh --json
minsync-sync-failedMinSync indexing failed; the message carries MinSync's own reasonFix the reported cause, then autorag refresh --method minsync
minsync-file-skippedMinSync skipped one file (unreadable, unparsable, or rejected by the embedder) and kept its older chunks; retried on the next syncFix that file's permissions/content, then autorag refresh --method minsync
minsync-lock-heldAnother minsync run holds .minsync/lock, often an orphan left by a killed host; retryableWait for it to finish or stop that minsync process, then autorag refresh --method minsync
embedder-unavailableNo remote endpoint answered, no minsync serve daemon could start, and the in-process addon is missing or failedRun minsync serve by hand to read its error, install MinSync (cargo install minsync) or @nomadamas/minsync-native, or configure a remote minSync.embedder
embedding-identity-mismatchIndexed vectors use a different embedderautorag index rebuild --method minsync
embedding-unavailableA datasource sidecar could not embed (same cause as embedder-unavailable)Start the daemon or install the addon, then re-sync that datasource
jikji-unavailableJikji binary missing or install failedCheck the Rust toolchain, retry autorag refresh --method jikji
jikji-unsupported-versionA jikji older than the pinned version was found and not run; the message names the version and pathautorag refresh --method jikji installs the pinned build, or upgrade it yourself
jikji-prepare-failedJikji prepare of a root failed (e.g. per-root timeout); the refresh still finishes and other roots indexBound the per-file/root budget (jikji.timeoutMs, jikji.prepareTimeoutMsPerFile), then retry
jikji-discover-failedA jikji_find miss whose retry step failed; the message carries the CLI exit status and stderr verbatimRead the quoted stderr; the failed root is dropped and healthy roots still answer
everything-index-failedWindows Everything instance could not start or index; the message carries the ES exit code and stderrFix the reported cause, then autorag refresh --method everything --json
fsearch-index-failedThe macOS/Linux fsearch-cli index could not be builtCheck fsearch-cli, then autorag refresh --method fsearch
datasource-index-failedBacking CLI failed to indexRun that CLI's own doctor from the table above
datasource-emptyStore has no matching contentRe-sync with the CLI, or accept as empty
datasource-auth-errorDatasource credentials missing or rejectedReport the environment-variable name; never its value
datasource-rate-limitedDatasource quota exhaustedWait and retry, or raise the quota with the provider
unknown-datasource-skillConfig key is not a known template and has no "type"Fix the name or add "type": "<template>"
retrieval-method-failedOne method errored during the queryRead --debug diagnostics; the message carries the method's own error
retrieval-source-missingWarning: hits whose source file was moved or deleted since the last refresh were skipped; the other hits are returnedRun autorag refresh to drop the stale entries
rerank-disabledWarning: rerank names no model, so reranking is off and each source contributes its own top 10Set rerank.model to turn it on, or remove the block; nothing else is wrong
mass-delete-suppressedA refresh would delete too large a share of indexed documentsInvestigate the search root, then autorag refresh --force if the deletion is intended
walk-truncatedThe directory walk hit its entry/depth cap under a rootRaise refresh.maxScannedEntries / refresh.maxDepth
search-root-unavailableA search root is missing, unlistable, or empty while it previously held documents; mirrors keptRestore the root, then autorag refresh
parser-warningkordoc parsed a file with a warning; the file is still indexedInspect the warning; fix the source if the parse matters
decision-model-unavailableThe session decision model (Jev) cannot answer; autorag search exits 3Sign in with /login or set OPENROUTER_API_KEY; the reason names what failed
decision-model-fallbackJev was unavailable; the session ran on the fallback small chat modelFix Jev's credential, or keep the fallback intentionally
query-route-fallbackJev routing unavailable; searched local with the original questiontest -n "$OPENROUTER_API_KEY"; report the env var name, never its value
datasource-selection-fallbackJev's per-datasource check unavailable; no datasource searched before the fast answerSame as query-route-fallback
query-decomposition-failedDecomposition model call failed; searched the original questionCheck queryDecomposition.model resolves (autorag models list --provider openrouter)
follow-up-check-fallbackJev post-fast-answer check unavailable; the run verified anywaySame as query-route-fallback
evidence-judgment-fallbackPost-answer evidence judgment unavailable; nothing was stored to memorySame as query-route-fallback
citation-without-resultA cited [eN] matched no recorded evidence; the citation was removed from the persisted answerRe-run with --debug to see the retrieval diagnostics
organize-skill-unavailableAn organize request could not load the packaged organize skill; fell back to localRe-install/repair the package so the packaged skill is present
query-routed, datasources-selected, follow-up-skippedInfo: Jev's branch and queries / datasources searched and skipped / the fast answer was judged finalNone; working as intended. A datasource never selected usually needs a clearer description in the config

Repair procedures ​

Stuck or missing embedding daemon ​

AutoRAG owns no lock or pid file for embeddings. A running minsync serve publishes host, port, and pid under ~/.cache/minsync/serve/<instance>/ and removes them on a clean stop; a leftover file from a crashed daemon is harmless (AutoRAG only adopts a daemon whose GET /health answers as a loopback server of the wanted model).

bash
ls ~/.cache/minsync/serve/* 2>/dev/null
autorag setup --format json

AutoRAG never starts the daemon. Run minsync serve --idle-timeout 0 by hand (or as a launchd/systemd service), read its own error, or press Ctrl+Shift+E in the TUI. The daemon stops itself after --idle-timeout seconds (default 300), so a semantic failure after a quiet spell usually means it timed out. Stop an orphaned daemon by the pid from ~/.cache/minsync/serve/<instance>/pid only after confirming no live refresh holds it.

Index locks are owned by their engines: MinSync/tantivy locks under <workspace>/.autorag/, per-CLI locks such as <workspace>/.autorag/datasources/discrawl/.discrawl-sync.lock. Delete one only after confirming no owning process is alive.

Orphan process ​

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

A refresh killed mid-run can leave a minsync serve daemon or a minsync child alive. A daemon idle-stops itself; stop a confirmed orphan by the pid above. Never stop a process another clone started. Re-run autorag status --json afterwards to confirm inFlight: false.

Embedding model mismatch ​

embedding-identity-mismatch or a dimension error means the vectors on disk were built with a different embedder than the configured one. Vectors of two different dimensions can never be compared, so the index must be rebuilt:

bash
autorag index rebuild --method minsync

The default is MinSync's local Qwen/Qwen3-Embedding-0.6B engine at 1024 dimensions, reached through a running daemon or MinSync's in-process engine (both report the identity provider: minsync). Changing the embedder's dimension in config without a rebuild leaves retrieval silently empty.

Stale index ​

stale-index diagnostics or stale: true mean sources changed after the last refresh.

bash
autorag refresh --method parsed,minsync --json
autorag refresh --force --json      # only when incremental refresh does not clear it

A file the parser failed on (corrupt PDF, encrypted HWP) or that was unreadable is not re-parsed on every refresh; it is skipped until its mtime, size, or parser version changes. After fixing the cause, retry those files once:

bash
autorag refresh --retry-failed --json

For continuous freshness install an hourly autorag watch --once job (cron, launchd, systemd timer, or Task Scheduler).

Missing or wrong setup ​

  • unknown-datasource-skill: the config key is not a builtin template and has no "type". It is skipped, not fatal — fix the name or add "type".
  • A configured datasource that returns nothing is a native store, connector, or query problem — every configured connection is searchable. Run its native check from the table above.
  • A missing MinSync binary is not a diagnostic: autorag search, autorag refresh, and the MCP tools fail with MinSync is required ... and a non-zero exit. Install it (cargo install minsync) or leave minSync.autoInstall on, then retry.
  • For browser history, autorag setup --format json reports installed, running, and embedding for Hister with a remediation per problem; autorag setup --sync-hister shares AutoRAG's embedding model with Hister (and refuses a remote or in-process backend).

If the CLI itself is missing or no config exists, run the installation and quickstart flow first — repair assumes an existing install.

Report ​

Always end with this table, one row per datasource and per AutoRAG component:

SourceConfiguredIndexedSearchableIssue foundFix applied
minsyncyesyesyes (3 hits)––
discordyesyesnostale archivediscrawl sync
telegramno––CLI not installedreported

Searchable must come from an actual query, never inferred from index state. Follow the table with the exact remaining action for every row that is not fully green.

Released under the Apache-2.0 license.