Prerequisites
- The plan that should process the documents is active: the fixed plugin version is activated (see Upgrade or switch a plugin), or the plan was rolled back.
- A key of the Organization that owns the Corpus with the actions
plugins:admin,operations:read(to follow the reprocess) andoperations:write(to pause, resume or cancel it), inQUIVR_OPERATOR_KEY.
Steps
1
List the stuck documents
stage is the step that failed: normalization (the normalizer failed, so the document was kept as submitted) or ingestion (segmenting or embedding it was refused or stopped). Filter with corpus_id, plugin, code, quarantined_after and quarantined_before; page_cursor returns the next page. A document quarantined before Quivr recorded structured reasons has only its code and no plugin. A document whose Record got a newer revision, or was withdrawn, is not listed: it can never become current.Keep the Corpus id and the code you want to reprocess:2
Count them
A dry run is required. It counts the documents the reprocess would take, by the stage that failed and by code:Leave out
code to take every stuck document of the Corpus, or narrow with plugin, quarantined_after and quarantined_before.By default, reprocessing starts at the step that failed. If a fixed normalizer must replace output that ingestion refused, add "from_stage": "normalization" to both the dry run and the start request. Quivr reads the stored source Blob, normalizes it with the accepted plan, publishes its new Manifest, then runs ingestion. The Version keeps its identity. The dry run still groups documents by their original failed stage.Only source Blobs whose Manifest has not yet been divided into search segments can be published again. Other inputs stay quarantined and count as skipped_not_republishable. Use a fresh idempotency key when changing the restart stage.3
Start it
Send the same body with The answer is an Operation, Quivr’s record of a long-running administrative task. It takes the documents in scope at this moment and runs them with the plan active now. The same key, filters and restart stage return the same Operation. Keep its id:
dry_run set to false:4
Follow it
versions_recovered are searchable now. versions_quarantined failed again and stay quarantined with their new reason. versions_skipped counts the Versions it left as they were, each under skipped_<reason>:Pause, resume or cancel it with
POST /v0/operations/{id}/pause, /resume or /cancel. Use /rerun on a finished reprocess to take what is still stuck in the same scope and preserve the restart stage, with the plan active then. Each request takes an idempotency_key body.Check it worked
List the Corpus again: the recovered documents are gone, and those that failed again show their new reason.What a reprocess does
- Normalization stage, or
from_stage: normalization. The normalizer of the active plan runs again. When it answers, the document is published with the normalized content, as it would have been the first time, and processed. The change feed announces it withrecord.materialized. - Ingestion stage. The ingestion plugin of the active plan segments and embeds the document again.
- As a first success. A recovered document becomes its Record’s current Version if the Record still wants it, is searchable, is evaluated by the alerts of its Corpus, and appears in the change feed with
record.retrieval_readyandrecord.enrichment_available. - Pace. It runs on the backfill queue, at most
backfill.rateVersions per second (see Configuration), so live ingestion keeps its capacity. One reprocess of a Corpus runs at a time. - Plan. It is pinned to the plan active when it was accepted, like other work. Temporary plugin unavailability retries with backoff; an execution-equivalent ingestion registration can serve it. Semantic changes require the original build or a new operation using the active plan.
- Interruptions. A restart resumes the document it was processing. Canceling it puts a document it had started back in quarantine with its previous reason.
Troubleshooting
Recover work stranded by an earlier plugin update
Earlier engine versions could quarantine Versions withpinned_plugin_unavailable
when an in-place plugin update changed its manifest digest. Upgrading prevents
new transport or discovery outages from causing this quarantine, but does not
release existing holds.
For a stranded Corpus rebuild, cancel its Operation and wait for cancellation to
finish. Start a new rebuild with POST /v0/corpora/{corpus_id}/rebuilds under the
active plan, following Switch a vector model.
Then follow the dry-run and reprocess steps above with the same Corpus id and
code: pinned_plugin_unavailable. Use fresh idempotency keys and confirm that
the rebuilt Corpus and recovered Versions are searchable.