Skip to content

Refresh operations ​

This page documents what autorag refresh reports when part of a run fails, how it protects against losing documents, how it is cancelled, and how it records progress and retries.

Running a refresh ​

bash
autorag refresh --method parsed,minsync --json

--force re-indexes even when the mirror looks unchanged, and also lets the mass-deletion valve delete what it would otherwise suppress. --retry-failed retries files whose parse or read failed earlier, once, even if they are unchanged. The command is model-free and exits 0 on success, 2 on a config error, and 1 on a runtime error. SIGINT/SIGTERM exit 130/143.

Refresh diagnostics ​

Every diagnostic carries a stable code, a severity (info, warning, or error), a message, and a source. Human output prints diagnostics when the run did not fully succeed, or always with --debug; the JSON envelope always carries them.

Per-file parse and source diagnostics (an error in one file never stops the run):

CodeSeverityCause
source-vanishedinfoThe source was deleted or replaced after the scan (ENOENT, ENOTDIR, EISDIR). Its mirror is removed.
source-unreadablewarningThe source could not be read (EACCES, EPERM). Paced with a skip record until the source, parser, or retry policy changes.
source-read-failedwarningA read error not listed above (EMFILE, EIO, EBUSY, ETIMEDOUT, …); reason carries the errno code.
source-changedwarningThe source identity changed during parsing; no completion is committed and the next refresh retries it.
parser-failedwarningkordoc, spreadsheet, CSV, PPTX, or EML parse failed, timed out, overran its heap, or its worker crashed.
parser-crashedwarningThe parser threw a plain Error or a non-ParseError value; reason carries the error name. The message is withheld because it may contain a path.
parser-skippedwarningThe source exceeds the parse-size cap (default 50 MiB), or an image is too small to OCR.
parser-warningwarningA parser emitted a non-fatal warning (kordoc warnings, a truncated sheet).
mirror-write-failedwarningWriting the parsed mirror failed; reason carries the errno code.
duplicate-excludedinfoAn older exact duplicate was excluded; the newest copy remains indexed.
cloud-placeholder-skippedinfoA File Provider placeholder whose provider has no verified release path was not read; reason carries the provider.
cloud-evict-failedwarningThe file was indexed but its local copy could not be released after the retries; the message carries the release helper's error and attempt count.
cloud-fingerprint-failedwarningA cloud or network file was indexed but its duplicate fingerprint could not be read or saved. It stays indexed and does not take part in exact-duplicate exclusion.

Refresh-run diagnostics:

CodeSeverityCause
search-root-unavailablewarningA search root was skipped before walking (see below). source is the opaque root prefix and reason is gone, not-a-directory, unreadable, or empty.
mass-delete-suppressedwarningThe run would delete more than the allowed share of indexed documents (see below). Nothing was deleted.
walk-truncatedwarningA root exceeded maxScannedEntries or maxDepth; reason is max-entries or max-depth, and unreached mirrors were kept.
directory-unreadablewarningA subdirectory could not be listed; its mirrors are kept and its siblings still index.
minsync-file-skippedwarningMinSync skipped a file it could not read, chunk, or embed; its previous chunks are kept and it is retried.
minsync-sync-failederror/warningA MinSync sync failed, or a per-file sync warning after a partial failure.
minsync-lock-helderrorAnother sync owns the index (a minsync run outlived its host and left .minsync/lock). Retryable: run refresh again.
minsync-staging-excludedwarningA parsed-mirror id could not be staged into the MinSync workspace (no canonical source-id form, or a missing parsed output).
embedder-unavailablewarningNo embedding backend answers, so semantic search is unavailable. autorag setup and autorag status report why.
embedding-identity-mismatcherrorA stored vector identity disagrees with the configured embedder; the fix is a full reindex.
refresh-interruptederrorA previous refresh stopped before it completed (recorded progress is running but the owner pid is gone).
watch-failed / watch-limitedwarningA filesystem watcher could not be established, or the watcher cap was hit.

Unavailable search roots and mass deletions ​

A parsed refresh never treats a search root it cannot see as proof that its documents are gone. Before walking, each root is probed. A root that no longer exists (gone), is no longer a directory (not-a-directory), cannot be listed (unreadable), or is empty although it previously held indexed documents (empty) is skipped: its previous mirrors and skip records stay untouched, and the run records one search-root-unavailable warning. deleted-mirror is never emitted for these roots. Healthy roots in the same refresh are still indexed and still delete their genuinely stale mirrors. A forced refresh (autorag refresh --force) treats an empty root as intentionally emptied.

A refresh that would delete more than refresh.maxDeleteRatio (default 0.3) of the indexed documents, and more than 100 of them, is refused: nothing is deleted and one mass-delete-suppressed warning is recorded. The next refresh repeats the check; a forced refresh deletes them.

The directory walk is bounded by refresh.maxScannedEntries (default 2000000 entries per root) and refresh.maxDepth (default 64). Hitting either records a walk-truncated warning and keeps mirrors for anything the walk did not reach. A single unreadable subdirectory records directory-unreadable, keeps the mirrors beneath it, and does not stop its siblings.

json
{ "refresh": { "maxDeleteRatio": 0.3, "maxScannedEntries": 2000000, "maxDepth": 64 } }

Transient read retries ​

EMFILE, EBUSY, EIO, and ETIMEDOUT are retried with doubling backoff (50 ms, 100 ms, 200 ms) before the file is skipped. The retry count is refresh.transientRetries (default 3; 0 disables retries).

json
{ "refresh": { "transientRetries": 3 } }

Unlike permission-denied failures, these are recorded without a retry deferral, so the next refresh retries them. Mirror writes go through a temp file removed on failure, so a failed write leaves no *.tmp orphan.

A write failure that makes the workspace itself unusable (ENOSPC, EDQUOT, EACCES, EPERM, EROFS) is not a per-file problem and aborts the refresh with a MirrorWorkspaceError naming the workspace. Files already mirrored in that run stay in the index, so the next refresh resumes incrementally.

Cancelling a refresh ​

SIGINT and SIGTERM abort a refresh. The signal is forwarded to the MinSync init, check, and sync processes: the running minsync and every descendant it started are stopped (SIGTERM to the process group, SIGKILL after 5 seconds), the config.toml this run rewrote is restored, and refresh rejects with the signal's reason. On POSIX each MinSync process leads its own process group, so the host also reaps it on SIGINT, SIGTERM, SIGHUP, and exit; Windows uses taskkill /t. Only the MinSync phase observes the signal so far; parse, datasource, and Jikji phases do not.

A minsync run that outlives its host (for example after the host is SIGKILLed, which no handler can catch) keeps .minsync/lock. The next check or sync exits 3, which AutoRAG reports as the retryable minsync-lock-held diagnostic instead of a generic failure.

Progress and liveness ​

AutoRAG runs minsync sync --progress jsonl. Each MinSync start, batch, heartbeat, and done event updates <workspace>/.autorag/refresh-progress.json with minsync: { synced, total }, advances updatedAt, and is also emitted through AutoRAGAgent.refresh(..., { onProgress }). MinSync's heartbeat interval defaults to five seconds.

A stale updatedAt between events means the phase is still running; it is not proof of a hang. Use the owner pid through autorag status's progress.ownerAlive for liveness, and use advancing progress to tell active work from a stalled batch. Progress is written every 25 files during parsing; it is a display marker, not the engine's recovery checkpoint.

Skipped files (partial sync) ​

MinSync skips a file it cannot read, chunk, or embed instead of aborting the sync, and exits 6 with partial: true and a files_failed list. AutoRAG treats that as a completed sync (minsync.ok: true) and reports each skipped file as a minsync-file-skipped warning whose source is the path inside the MinSync workspace. The count appears as minsync.filesSkippedCount in the result, minsync.filesSkipped in the completed refresh-progress.json, and skipped=N / filesSkipped=N in human output. MinSync keeps the file's previous chunks and retries it on the next sync; a later successful retry omits the count again. Only an exit 6 without a partial report is a minsync-sync-failed.

Retry and failure behavior ​

During a MinSync-backed refresh, three consecutive unsuccessful sync runs with the same structured reason and diagnostic code stop further MinSync work. Missing fields compare consistently; changing only the error message does not reset the count. A different reason or code starts a new streak, and any successful sync (including one with per-file skips) clears it. A held index lock stops immediately.

Parsing overlaps indexing, so in-flight parsing may finish its current batch before observing the stop at the next committed-batch callback. There is no final retry after the threshold. Committed mirrors and the durable stage journal remain available: fix the reported cause and run autorag refresh --method minsync again to resume incrementally without reparsing unchanged committed sources. Deletions remain deferred until the final parse batch.

A systemic stop reports one MinSync component failure in each diagnostic list, preserving the terminal cause and original error text. Other failed runs retain at most 100 per-file sync warnings plus one summary with the omitted count. A later successful sync clears these warnings and the omitted count.

Migration and identity ​

A MinSync workspace keeps its state in the .minsync subdirectory of <workspace>/.autorag/minsync, alongside the sync cursor and config.toml. The embedding identity includes provider, model, immutable model revision, dimension, query prefix, and passage prefix. A mismatch in any field except the query prefix requires a full reindex; the query prefix only shapes query vectors, so changing it is recorded without re-embedding documents. A dimension mismatch is detected before vector reuse.

An identity mismatch is reported as embedding-identity-mismatch; the fix is a full reindex of the affected store. To rebuild a MinSync workspace:

bash
autorag index rebuild --method minsync

autorag index reset --method minsync --yes followed by autorag refresh --method minsync has the same effect. A MinSync workspace created through the old embedding gateway (a tei:/.gguf id, or an old profile field) must be rebuilt this way; vectors from that removed runtime are not compatible. Legacy profile and .gguf ids in config.json are ignored on read, without an error. See Embedding backends.

Released under the Apache-2.0 license.