How to Fix MongoDB Error 189 (PrimarySteppedDown)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 189 when a replica set primary steps down during an operation. You fix it by retrying the operation on the new primary node and stabilizing cluster elections. In the official error rules, code 189 is named PrimarySteppedDown. It belongs to both the NotPrimaryError and RetriableError groups. When a primary node loses its role, it stops taking writes right away. It also closes active client operations that need primary state. Because this error is retriable, modern client dr

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You see mongodb error 189 when a replica set primary steps down during an operation. You fix it by retrying the operation on the new primary node and stabilizing cluster elections.

In the official error rules, code 189 is named PrimarySteppedDown. It belongs to both the NotPrimaryError and RetriableError groups. When a primary node loses its role, it stops taking writes right away. It also closes active client operations that need primary state. Because this error is retriable, modern client drivers can handle transient stepdowns on their own.

What causes mongodb error 189 in replica sets

A replica set primary steps down for two main reasons. It either sees a planned maintenance request or loses contact with a majority of voting nodes. During a planned upgrade, an admin or cloud tool tells the primary to step down. The node drops to a secondary state so another member can take over.

Unplanned stepdowns happen when network splits or heavy server loads block heartbeats between nodes. If the primary cannot reach a majority of members in time, it steps down. This rule stops two nodes from taking writes at once during a network split. High CPU load, slow disk writes, or memory pressure can also stall a primary node. When other nodes stop hearing from the stalled primary, they hold a new election.

Client settings can also make this error show up in your app logs. If your client driver has retry behavior turned off, the app gets the raw error. Long transactions or slow write queries are also at higher risk during an election window. When the node steps down mid-query, the database aborts the running command and returns code 189.

How to diagnose and fix stepdown failures safely

Start by checking your database logs around the time of the error. Look for election messages, heartbeat timeouts, or planned maintenance events. This tells you if the stepdown was an expected upgrade or a sign of server stress.

When engineers inspect a live cluster, they do not need broad write permissions. MongoDB grants access through role-based authorization on a specific database down to the collection level. You can assign the built-in read role to let engineers check collection stats and database stats. The read role allows actions like find, listCollections, listIndexes, dbStats, and collStats without allowing data changes. It blocks insert, update, remove, and dropCollection actions, keeping production data safe during an incident.

MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

If the stepdown came from resource saturation, fix the underlying query load or hardware limit. Check if a heavy write job or missing index caused the primary to stall. Adding an index or tuning write workloads requires the readWrite role on that database. Wait until the cluster is stable before making index changes.

Next, check how your app handles retriable errors. Since PrimarySteppedDown is a RetriableError, make sure your client driver uses retryable writes and reads. When retry logic is active, the driver waits for the replica set to elect a new primary. It then resends the failed operation without waking up your on-call team.

Preventing repeated primary stepdowns in production

To stop frequent stepdowns, keep your network paths between replica set members fast and reliable. Place voting nodes in zones with stable links so brief blips do not trigger elections. Keep an odd number of voting members so the cluster can always form a clear majority.

Watch your disk queues and memory use during peak traffic hours. If a primary runs out of memory or disk throughput, it cannot answer heartbeats on time. Scaling your hardware or spreading read traffic to secondary nodes reduces pressure on the primary. You should also run planned maintenance during low traffic windows to limit aborted queries.

Add command guardrails and field masking beside MongoDB

Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev sits inline in the wire protocol beside your database as a sidecar for your MongoDB. For every command an agent or human sends in production, hoop.dev decides to pass, mask, block, or escalate it for review.

Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run or hold risky calls for approval, and data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.

Frequently asked questions

Is mongodb error 189 safe for my app to retry?

Yes, code 189 is marked as both a NotPrimaryError and a RetriableError. Modern client drivers can retry the failed operation once the replica set elects a new primary.

Why did my primary node step down without a server crash?

A primary steps down whenever it cannot reach a majority of voting nodes in time. Network blips, high load, or planned maintenance commands all cause a clean stepdown without a crash.

What database role do I need to inspect a cluster after a stepdown?

Use a role with read-only privileges, such as the built-in read role on the target database. It lets you run dbStats and collStats to check health without risking accidental writes.

The query runs. The emails stay hidden.