Change Feed continuity after a failed upgrade to Cosmos DB API v2.0.0 Full Fidelity mode

Answer

The Change Feed processor does **not** automatically reconcile its checkpoints after a rollback from API v2.0.0 Full Fidelity mode to the legacy API.

Likely explanation

When the upgrade fails, the processor may have already written lease documents using the new SDK while still targeting the legacy API after rollback. The lease token format is unchanged, but the processor’s internal continuation token can become stale or mismatched, causing it to either restart from the beginning or throw a lease‑mismatch error.

Confirmed facts

• The lease container (default name leases) stores continuation tokens and is **not** altered by switching between API versions; the lease schema is identical for legacy and Full Fidelity modes.
• If the lease container remains intact and contains valid lease documents, the processor can resume from the last saved token once the SDK is re‑initialized.
• Azure Cosmos DB Change Feed guarantees at‑least‑once delivery; exactly‑once processing depends on the application’s idempotency, not on the feed itself.

Steps to restore continuity

1. Verify the lease container exists and inspect its documents:

   az cosmosdb sql container show \
     --account-name  \
     --resource-group  \
     --database-name  \
     --name leases \
     --query "id"

   Then list a few lease items to see Owner and Continuation fields.
2. Ensure the application uses the **same** lease container name and ownership settings (e.g., LeaseOptions.LeasePrefix) that were used before the upgrade.
3. Restart the Change Feed Processor host with the SDK version that targets the legacy API (or the same version you intend to run). The host will read the existing lease tokens and continue from the last checkpoint.
4. Watch the processor logs for messages such as Lease acquired and the continuation token value. If you see Lease lost or Renew failed errors, the lease may be corrupted.
5. If the lease documents show Owner=null or missing Continuation tokens, consider **resetting** the lease container (delete lease documents) and let the processor re‑acquire leases, accepting that pre‑upgrade changes will be reprocessed.

Missing diagnostic detail

To decide whether a simple restart suffices or a lease reset is required, we need to know: What is the current state of the lease container after the failed upgrade? Specifically, are any lease documents missing the Owner field or have stale Continuation values? This detail changes the recommendation from “restart only” to “reset lease container”.