> For the complete documentation index, see [llms.txt](https://atomic-blend.gitbook.io/mongo2pg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atomic-blend.gitbook.io/mongo2pg/operating-a-migration/operations/handling-quarantine.md).

# Handling quarantine

Quarantined rows block cutover **by design** — see [Quarantine](/mongo2pg/concepts/concepts/quarantine.md) for why, and what parks a document in the first place. This page is the operating procedure for clearing one out.

## The procedure

```mermaid
flowchart TD
    Q0["document quarantined<br/>(coercion or ref failed)"] --> Q1["mongo2pg quarantine list<br/>--collection c"]
    Q1 --> Q2["mongo2pg quarantine list<br/>--reason r<br/>read the field + reason"]
    Q2 --> D{"data bug,<br/>or mapping gap?"}
    D -- "document holds a<br/>value it should not" --> F1["fix the DOCUMENT in MongoDB"]
    D -- "shape is legitimate,<br/>mapping has no rule for it" --> F2["fix the MAPPING<br/>(hot-reloadable)"]
    F1 --> R["mongo2pg quarantine retry<br/>--collection c<br/>re-reads the CURRENT document"]
    F2 --> R
    R --> V["mongo2pg quarantine list<br/>confirm it cleared"]
    V -- "still parked" --> Q2
    V -- "cleared" --> S["mongo2pg status<br/>cutover ready?"]
```

```bash
# 1. See what's parked, worst offenders first.
mongo2pg quarantine list --collection time_entries

# 2. Understand why — the reason names the field and the coercion or resolution that failed.
mongo2pg quarantine list --collection time_entries --reason "no rule matched"

# 3. Fix the DOCUMENT in MongoDB, or fix the MAPPING if the shape is legitimate and
#    just not yet declared.
mongosh time_entries.updateOne({_id: ObjectId("66f1a2...")}, {$set: {duration: "PT90M"}})

# 4. Re-run the current mapping against the current state of the document.
mongo2pg quarantine retry --collection time_entries

# 5. Confirm it cleared.
mongo2pg quarantine list --collection time_entries
mongo2pg status
```

`quarantine retry` **re-reads the current version of the document from MongoDB** — it never retries against a stale copy captured at the time of the original failure. So step 3 has to happen first: retrying before fixing anything just reproduces the same failure and bumps the `attempts` counter on the same row.

## Two kinds of fix

* **Fix the data.** The document genuinely holds a value the mapping cannot and should not accept — a garbage string in a duration field, an `_id` reference that points at nothing. Fix it at the source.
* **Fix the mapping.** The document's shape is legitimate but the mapping does not yet declare a coercion rule for it — e.g. a collection turns out to hold a fourth timestamp encoding nobody had seen yet. Add the rule (`mongo2pg schema plan` and a hot-reloadable mapping change apply it without a restart — see [The mapping file](/mongo2pg/concepts/concepts/mapping-file.md#hot-reload)), then retry.

## Exporting for offline triage

```bash
mongo2pg quarantine export --out quarantine.jsonl
mongo2pg quarantine export --out quarantine.jsonl --include-opaque   # real ciphertext values, not redacted
```

Every `opaque` field is redacted by default — the key stays present with a placeholder value, so an operator can see the field existed without exposing PII or ciphertext in an exported file. Reach for `--include-opaque` only when the person running the export is authorized to see the real values.

## A growing quarantine is a signal, not an emergency

One parked document does not stop the migration; the pipeline keeps running and cutover simply stays blocked until it is resolved. A *growing* quarantine, on the other hand — many documents failing the same rule — usually means a mapping gap rather than N independent bad documents. The `Mongo2pgQuarantineGrowing` alert fires on exactly that pattern (see [Alerts](/mongo2pg/observability/observability/alerts.md)), and the per-`(collection, field, reason)` grouping in `quarantine list` is the fastest way to find the one mapping fix that clears most of the list at once.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://atomic-blend.gitbook.io/mongo2pg/operating-a-migration/operations/handling-quarantine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.