Solution skill
Azure Cosmos DB multi-region: consistency, failover priority, and testing it
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=1The fix
Setup:
- 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.
- 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. - 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.
- 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-changeto 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_locationsin 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>