How to Fix MongoDB Error 135 (StaleTerm)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 135 when a node sees an outdated election term. You fix this StaleTerm failure by refreshing cluster metadata and checking network links. In a replica set, every election bumps a counter called the term. Nodes check this term number on every internal message they receive. When an old primary node sends commands with a past number, receivers reject it. This rule stops split-brain writes and keeps your data safe during failovers. What causes mongodb error 135 in replica se

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 135 when a node sees an outdated election term. You fix this StaleTerm failure by refreshing cluster metadata and checking network links.

In a replica set, every election bumps a counter called the term. Nodes check this term number on every internal message they receive. When an old primary node sends commands with a past number, receivers reject it. This rule stops split-brain writes and keeps your data safe during failovers.

What causes mongodb error 135 in replica sets

The engine maps code 135 to the StaleTerm name. It shows up when replica set members disagree on who leads the cluster. Network drops are the most common trigger for this state. A primary node might lose contact with the rest of the cluster. The remaining nodes hold a new election and pick a new leader. That election raises the term number across the healthy side of the network.

When the old primary comes back online, it still holds the old term. It tries to replicate writes or send heartbeats using that outdated number. Other nodes spot the lower term and throw the StaleTerm error right away. Once the old leader sees the higher term, it steps down to secondary.

Heavy disk lag or paused virtual machines can also trigger this issue. If a node freezes during high load, it misses election updates. When the node wakes up, its local state is behind the cluster. Client drivers or internal threads that cache old topology data also hit this code.

How to diagnose and fix StaleTerm errors safely

Start your check by reading the server logs on all replica set nodes. Look for recent election events, network timeouts, or heartbeat failures between hosts. You do not need full admin rights to check basic database health. MongoDB uses role-based rules that grant actions down to the collection level. The built-in read role lets you run database stats and collection stats safely. It blocks insert, update, remove, and drop actions so engineers cannot break data.

Next, check the network path between your database hosts. Fix any dropped packets, firewall blocks, or DNS delays between replica set members. Make sure every host clock uses time sync so heartbeats stay on schedule. If one node stays stuck, let it finish its step-down process cleanly. Do not force a manual reconfig while the network is still shaky.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Check your app drivers if the error shows up in client logs. Modern drivers refresh their cluster view when they hit a state change. If an app holds stale sockets, restart the worker pool to clear old sessions. Keep write concerns set to majority so apps wait for valid leaders.

Preventing term mismatches during routine maintenance

Planned work often triggers term errors if teams rush node restarts. Always step down the primary node cleanly before you patch or reboot it. A clean step-down forces a fast election and updates the term on all nodes. Wait for the cluster to name a new leader before stopping the next host.

Watch host CPU and disk queues during peak traffic hours. When disk writes stall, a primary node cannot answer heartbeats on time. Other nodes assume the leader died and start a new election. Keeping disk latency low prevents false elections and stops StaleTerm spikes before they start.

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

Does StaleTerm mean my database lost data?

No, this error actually prevents data loss during a split-brain event. It blocks an old primary from writing data after a new leader takes over.

Can I check replica set stats with a read-only role?

Yes, the MongoDB read role allows database and collection stats commands. Your team can inspect state without having rights to modify or drop data.

Why does StaleTerm happen during cloud maintenance?

Cloud host pauses or brief network cuts isolate the primary node. The rest of the cluster elects a new primary and raises the term number.

The query runs. The emails stay hidden.