How to Fix MongoDB Error 343 (ShardCannotRefreshDueToLocksHeld)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 343 when a shard cannot refresh its routing data. Held database locks block the shard from updating its metadata state. You can fix this by clearing long operations and retrying the failed request. Root causes of mongodb error 343 in sharded clusters In the database engine, code 343 maps to the ShardCannotRefreshDueToLocksHeld failure name. Sharded clusters track data placement across nodes using shared routing metadata. Each shard must refresh its local copy of this rou

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 343 when a shard cannot refresh its routing data. Held database locks block the shard from updating its metadata state. You can fix this by clearing long operations and retrying the failed request.

Root causes of mongodb error 343 in sharded clusters

In the database engine, code 343 maps to the ShardCannotRefreshDueToLocksHeld failure name. Sharded clusters track data placement across nodes using shared routing metadata. Each shard must refresh its local copy of this routing map often. A refresh needs a specific internal lock on the target collection.

If another operation holds a conflicting lock, the refresh cannot finish. The shard then stops the refresh attempt and returns code 343. Heavy write loads or schema updates often hold these locks too long. For example, creating or dropping an index locks the target collection.

Dropping a collection or modifying a collection also holds strong locks. Long multi-document transactions can keep locks open across shards as well. When a router sends a query during these tasks, the shard checks its version. If the version is old, the shard tries to refresh and hits the lock.

How to diagnose and fix lock conflicts safely

First, check your active database operations to find what holds the lock. Look for long queries, index builds, or schema changes on the affected shard. Do not grant full admin rights to every engineer during an incident. MongoDB grants access through role-based rules down to the collection level.

Give your on-call team a read role for basic inspection tasks. The read role allows actions like find, listCollections, listIndexes, dbStats, and collStats. It does not allow insert, update, remove, or dropCollection actions on data. This keeps production data safe while engineers check collection and index states.

If a bad write job holds the lock, let the task finish first. If the task is stuck, a team member with proper rights can stop it. Avoid running actions like createIndex, dropIndex, or dropCollection during peak traffic hours. Schedule heavy readWrite tasks during quiet windows so shards can refresh freely.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Preventing metadata refresh stalls in production

You can reduce lock stalls by keeping transactions short and well scoped. Break large batch updates into smaller chunks so locks clear between runs. Ensure client apps retry queries when they get a temporary lock error.

Also review who has the readWrite role in your production databases. The readWrite role allows insert, update, remove, createCollection, and index changes. Limit those actions to automated deployment pipelines or approved maintenance sessions. When humans inspect live data, mask sensitive fields like emails or card numbers in results. Rewriting matched fields like phone numbers or national IDs protects privacy during debugging.

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

What does ShardCannotRefreshDueToLocksHeld mean in plain terms?

It means a shard tried to update its data map but could not. Another running task held a lock on the database or collection at that time.

Does mongodb error 343 cause data loss on the shard?

No, this error does not corrupt or delete your stored records. The shard simply rejects the current request to prevent reading stale routing data.

Which database operations usually block a shard metadata refresh?

Tasks like createIndex, dropIndex, createCollection, and dropCollection often hold strong locks. Long transactions or unindexed bulk updates can also delay a metadata refresh.

Teams that document these role rules and review logs each month catch config drift early. Clear ownership for each role keeps live systems simple to run and easy to audit across the whole team.

The query runs. The emails stay hidden.