How does members[n].priority affect which MongoDB replica set member becomes primary?

## What priority is Every member of a replica set carries a `priority` in its configuration entry — `members[n].priority` in `rs.conf()`. It is a number between 0 and 1000, and it defaults to 1, so a set built from defaults has all members equally preferred. Priority does not decide elections. Votes decide elections, and a candidate always needs a strict majority of the voting members regardless of how high its priority is. What priority does is shape *who stands* and *who the set converges on* when more than one member is eligible. ## Priority zero: ineligibility Setting `priority: 0` makes a member permanently ineligible for the primary role. Such a member: - performs initial sync and tails the oplog like any secondary, - can serve reads for clients using a non-primary read preference, - still votes in elections if its `votes` is 1, - can never be elected primary, and never calls an election of its own. This is the standard way to pin a member into a supporting role. A member in a distant region kept as a disaster-recovery copy, a member reserved for backups or analytics, a member on hardware too weak to carry the write workload — all get `priority: 0` so that a random failover never lands the primary somewhere you did not intend. MongoDB also enforces the pairing in the other direction: a member with `votes: 0` **must** have `priority: 0`. A member that cannot vote must not be able to trigger or win an election either, so the configuration is rejected if you set one without the other. ## Higher priority: takeover The more surprising behaviour is at the other end. The set does not merely tolerate a high-priority member; it actively converges on it. If a secondary's priority is higher than the current primary's, that secondary will call an election to displace the sitting primary. It does not do this immediately or blindly — it waits until its own oplog is close enough to the primary's, within roughly ten seconds, so that taking over does not throw away a large amount of recent history. Once that condition holds, it stands for election, and if it wins the majority the current primary steps down. This is called **priority takeover**, and it has two important consequences in practice: 1. **Raising a member's priority causes a failover.** An `rs.reconfig()` that bumps one member above the others is not a passive preference change; within seconds it produces an election, a brief write-unavailable window, and possibly a rollback of writes the old primary had not replicated to a majority. Treat a priority change as a scheduled operation, not a config tidy-up. 2. **The primary comes back to the preferred node.** After a failover to a lower-priority member, the set will move the primary role back to the high-priority member once that member is healthy and caught up. That is often exactly what you want — keeping the primary near the bulk of the clients or on the beefiest hardware — but it means one bad node can cause repeated flapping if it keeps failing and recovering. ## Priority is a preference, never a guarantee A high-priority member that is unreachable by a majority of voters wins nothing. A high-priority member whose oplog is far behind will not stand until it catches up. And if the high-priority member is down, the set elects the best eligible member available — priority does not make the set wait. The corollary is that priority cannot be used as a correctness mechanism. It cannot pin writes to a region, it cannot guarantee that a particular node holds the primary role at any given moment, and it must not be relied on for anything more than steering. ## Priority versus votes These two fields are frequently conflated. They are orthogonal: - `votes` (0 or 1, at most 7 voting members in a set) determines whether the member counts toward the majority arithmetic. - `priority` (0–1000) determines whether the member may become primary and how strongly the set prefers it. A member can vote but be ineligible (`votes: 1, priority: 0`) — a common configuration for a tie-breaking data-bearing node in a third location. The reverse, being eligible but non-voting, is not allowed. ## Designing with priority A typical layout gives the members in the main application region the default priority or slightly above, gives a remote disaster-recovery member `priority: 0` so a network event never moves writes across an ocean by accident, and leaves the rest at the default so any of them can take over. Distinct priorities among the main-region members express a preference order for which machine you would rather run writes on; identical priorities say you genuinely do not care and let the fastest responder win. When you do need to move the primary deliberately, `rs.stepDown()` on the current primary is the controlled tool — it gives secondaries a catch-up window and hands over cleanly — rather than shuffling priorities and waiting for a takeover to fire.