How to Fix MongoDB Error 11602 (InterruptedDueToReplStateChange)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 11602 when a database node changes its replica state mid-operation. You fix it by retrying the failed operation and checking your cluster health. In the official catalog, this fault is named InterruptedDueToReplStateChange. The database groups this event under Interruption, NotPrimaryError, and RetriableError. When a primary node steps down, it stops active tasks right away. This rule stops two nodes from taking writes at the same time. Your app sees the drop and gets the

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 get mongodb error 11602 when a database node changes its replica state mid-operation. You fix it by retrying the failed operation and checking your cluster health.

In the official catalog, this fault is named InterruptedDueToReplStateChange. The database groups this event under Interruption, NotPrimaryError, and RetriableError. When a primary node steps down, it stops active tasks right away. This rule stops two nodes from taking writes at the same time. Your app sees the drop and gets the error code back.

What causes mongodb error 11602 in a cluster

A replica set has one primary node and several secondary nodes. The primary node takes all write requests from your client apps. Sometimes that primary node loses network reachability to the other cluster members. Other times, a server restart or planned maintenance forces a role change. When this happens, the primary node steps down to become a secondary node.

Any command running on that node during the change gets cut off. The engine aborts those active reads and writes to keep data safe. It then sends the InterruptedDueToReplStateChange fault back to the client driver. Because this is a NotPrimaryError, the old node rejects new write tasks. Because it is also a RetriableError, the client driver can try again.

High memory use or disk delays can also trigger this state change. If a node cannot reply to heartbeats in time, peers start an election. The slow primary sees that it lost the vote and steps down. Long queries that hold locks during this shift will fail right away.

How to diagnose and fix the failure safely

First, check your client driver settings to confirm retry logic is active. Modern client drivers see the RetriableError tag and resend the task. They find the new primary node and run the write command again. If your app uses an older driver, you must add retry code.

Next, inspect the cluster logs to see why the primary stepped down. You do not need full admin rights to check basic database status. MongoDB uses role-based rules that grant actions down to the collection level. The built-in read role grants access to non-system collections in a database. It lets engineers run collection stats and database stats without write rights. It blocks actions that change data, like insert, update, or remove.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Give your on-call team a read role when they check replica faults. Never hand out the readWrite role just to look at cluster state. The readWrite role allows collection drops and index changes that risk uptime. Keep human sessions scoped to read tasks while you fix network drops.

How to stop state change errors during maintenance

Planned work on servers often triggers replica state transitions across the cluster. Before you reboot a server, tell the primary node to step down cleanly. A clean step-down gives running queries a short window to finish up. This small step lowers the number of interrupted tasks in your app.

You should also check the network path between all replica set nodes. Packet loss or firewall timeouts often cause false elections during peak load. Fix any slow disks so nodes never miss their heartbeat checks. When nodes stay healthy, your primary stays stable and queries finish cleanly.

Inspect MongoDB wire traffic in flight

Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.

First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.

Frequently asked questions

Is mongodb error 11602 safe to retry in my app?

Yes, the database marks this code as a RetriableError and NotPrimaryError. Your client driver can safely send the failed task to the new primary.

Does InterruptedDueToReplStateChange mean my database lost data?

No, the database aborts the running task to stop split-brain writes. You just need to repeat the aborted write on the new primary node.

What role should engineers use to check this error in production?

Engineers should use a role with read actions like database and collection stats. Avoid giving out write permissions when teams only need to check logs.

The query runs. The emails stay hidden.