How to Fix MongoDB Error 128 (LockNotFound)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 128 when the database cannot find an active lock. You fix this LockNotFound failure by retrying the operation and checking cluster health. Distributed databases rely on locks to keep data safe during big changes. When a process looks for a lock that is gone, the task stops. This keeps two servers from changing the same data at the same time. Knowing why locks vanish helps your team keep the database stable. What causes mongodb error 128 in your cluster The official data

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 128 when the database cannot find an active lock. You fix this LockNotFound failure by retrying the operation and checking cluster health.

Distributed databases rely on locks to keep data safe during big changes. When a process looks for a lock that is gone, the task stops. This keeps two servers from changing the same data at the same time. Knowing why locks vanish helps your team keep the database stable.

What causes mongodb error 128 in your cluster

The official database spec names this code LockNotFound. It happens when a node expects a lock record that does not exist. In a sharded cluster, a config server tracks locks for metadata tasks. If a network drop cuts off a node, the lock lease can expire.

When the slow node wakes up, it tries to finish its work. It checks for its lock, gets mongodb error 128, and stops right away. Clock drift between servers can also make a lock expire too soon. Long pauses from high memory use or disk wait cause the same issue.

Sometimes an admin clears a stuck lock by hand during an outage. The old worker thread still tries to refresh or release that missing lock. The database returns LockNotFound so the old thread does not corrupt live collections.

How to diagnose and fix LockNotFound in production

Start by checking your server logs around the time of the failure. Look for network drops, primary elections, or slow disk alerts on your nodes. Fix any clock drift across your hosts so all nodes share one time. Make sure your servers have enough memory and disk speed for peak loads.

You should not grant full admin rights to every engineer who investigates locks. MongoDB grants access through roles that allow specific actions on defined resources. A role applies to its database and works down to the collection level. Give your team the read role when they inspect state in non-system collections.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

The read role allows find, listCollections, listIndexes, dbStats, collStats, and changeStream actions. It leaves out insert, update, remove, and dropCollection so users cannot break locks. If an app needs to retry a failed write, use the readWrite role. The readWrite role adds insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection.

How to prevent lock failures during schema and balancer tasks

Run big index builds or collection changes during low traffic hours. High write loads slow down metadata updates and make lock leases time out. Keep your client drivers updated so they handle clean retries when elections happen. Watch your cluster metrics for long lock wait times before they cause errors.

Set clear timeouts on all client sessions so hung tasks stop on time. When a task fails with code 128, let the app wait and retry. A fresh request will ask for a brand new lock and finish cleanly. Good role rules and clean retries keep your data safe under heavy load.

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

What does LockNotFound mean in MongoDB?

LockNotFound is the official name for error code 128 in the database. It means a process tried to use or release a lock that vanished.

Does error 128 mean my data is corrupted?

No, this error actually stops data corruption before it can happen. The database halts the stale task so it cannot overwrite newer changes.

Which role should engineers use to check collection stats during lock issues?

Assign the built-in read role on the target database for safe checks. It grants dbStats and collStats actions without allowing any data changes or drops.

The query runs. The emails stay hidden.