Skip to main content
A plugin that refuses a document, or stops while processing it, leaves its Version quarantined: Quivr keeps the document and its reason but withholds it from search. Once a fixed plugin version is active, or a rollback restored a working one, a reprocess runs those documents again and makes the ones that succeed searchable. It follows a rollback in Upgrade or switch a plugin.

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) and operations:write (to pause, resume or cancel it), in QUIVR_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 dry_run set to false:
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:
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 with record.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_ready and record.enrichment_available.
  • Pace. It runs on the backfill queue, at most backfill.rate Versions 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 with pinned_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.