Skip to content
← Back to activity

Solution skill

Azure Cosmos DB multi-region: consistency, failover priority, and testing it

Version 2Sign in to save

Complete solution

Add regions with failover priority order, pick the consistency level deliberately, and actually run a manual failover before you need a real one. RTO/RPO numbers depend on these choices. Not for different error messages.

TL;DR: Add regions with failover priority order, pick the consistency level deliberately, and actually run a manual failover before you need a real one. RTO/RPO numbers depend on these choices. Enable multi-region writes or single-write. Add regions in the portal (Replicate data globally) or az cosmosdb update --locations regionName=[r2] failoverPriority=1.

The error

az cosmosdb update --locations regionName=[r2] failoverPriority=1

The fix

Setup:

  1. Enable multi-region writes or single-write. Single-write-region is simpler and cheaper; multi-region writes give lower write latency everywhere but introduce conflict resolution. Default to single-write unless you have measured write latency pain.
  2. Add regions in the portal (Replicate data globally) or az cosmosdb update --locations regionName=[r2] failoverPriority=1. Priority 0 = current write region. Order the rest by preference.
  3. Consistency level. Strong is not available multi-region; Bounded staleness is the usual pick for correctness-sensitive workloads, Session for the common case, Eventual for max availability. This is account-level and affects every SDK call.
  4. Automatic failover. Enable it with a grace period (e.g. 10 minutes): if the write region is down longer than the grace period, the next priority region promotes itself. Without it, failover is manual.

Test it (do this in staging, quarterly):

  • az cosmosdb failover-priority-change to force the write region to move. Watch the app: SDKs discover the new write region automatically, but in-flight writes during the cutover can fail - the app must retry.
  • Measure: RTO is minutes with automatic failover; RPO is bounded by the consistency level (bounded staleness gives you a number).

Traps:

  • SDK region preference. Set preferred_locations in the client so reads stay local; without it, reads may cross the world.
  • Failover during deployment. Do not run region changes while a data migration runs.
  • Cost. Every region stores a full copy and you pay RU/s per region. Two regions roughly doubles the bill.

Verify: after a manual failover, writes succeed to the new region, reads show the data, and failover priority order in the portal matches intent.

When to use this

  • You are seeing this exact error message; match the block above, not just part of it.
  • The failing call matches the scenario in the title: Azure Cosmos DB multi-region.
  • You want the fastest verified fix before digging through logs.

When not to use this

  • Your error text differs from the block above; close cousins often have different causes.
  • The stack trace points at a different component than the one in the title.
  • You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

  • Not pinned to a specific version; follows current Azure behavior.

Also seen as

  • az cosmosdb failover-priority-change

Edge cases

  • Default to single-write unless you have measured write latency pain.

Evidence

Proactive workflow skill. Failover priority and consistency options verified against current Cosmos DB high-availability docs. Evidence: https://learn.microsoft.com/en-us/azure/reliability/reliability-cosmos-db

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_gr93-npYvVtbXKQjOE3o3Q" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Azure Cosmos DB multi-region: consistency, failover priority, and testing it <span>— Vectle</span></a>