How to Fix MongoDB Error 319 (MovePrimaryInProgress)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 319 when an operation conflicts with an active primary shard move. To fix this MovePrimaryInProgress error, wait for the transfer to finish and retry your request. Sharded clusters assign one primary shard to each database for all unsharded collections. Moving that primary shard shifts unsharded data from the old shard to the new shard. During this move, the cluster blocks conflicting reads, writes, and schema changes. Root causes of mongodb error 319 in sharded clusters

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 319 when an operation conflicts with an active primary shard move. To fix this MovePrimaryInProgress error, wait for the transfer to finish and retry your request.

Sharded clusters assign one primary shard to each database for all unsharded collections. Moving that primary shard shifts unsharded data from the old shard to the new shard. During this move, the cluster blocks conflicting reads, writes, and schema changes.

Root causes of mongodb error 319 in sharded clusters

The database engine maps error code 319 to the MovePrimaryInProgress state. This state triggers when an admin starts a primary shard reassignment for a database. While the cluster copies unsharded collections across shards, it locks those target resources.

Client apps hit this error when they run writes or schema tasks during the move. For example, creating a collection, building an index, or dropping a collection will fail. Even some read requests can fail if routing rules update mid-flight.

Long transfers make this error show up more often in your app logs. Large unsharded collections take much more time to copy over the network. High disk load or slow links between shards also stretch the transfer window. If an app retries too fast without waiting, it will log hundreds of errors.

How to diagnose and fix the failure in production

Start by checking whether a primary shard move is still running on your cluster. Inspect the cluster logs and current running tasks to track the transfer progress. Do not kill the active move task or restart shard nodes during the copy. Stopping a move mid-flight can leave metadata and collection files out of sync.

While you check the cluster, use least-privilege access for your team. MongoDB uses role-based rules that grant actions down to the collection level. Give engineers the built-in read role when they only need to check collection stats. The read role allows find, listCollections, listIndexes, dbStats, and collStats without allowing data changes. Do not hand out full admin rights or readWrite roles just to check error logs.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Once the primary shard move finishes, the cluster updates its routing catalog. Tell your client apps to refresh their cluster metadata and retry the blocked requests. Adding exponential backoff to your app retry logic helps absorb brief lock windows.

Preventing primary shard move conflicts during maintenance

You can avoid MovePrimaryInProgress errors by planning shard moves before you run them. Check the size of all unsharded collections in the database before moving the primary shard. If a collection is huge, consider sharding it first or moving it during low traffic.

Pause background batch jobs and schema migration scripts before starting a primary shard move. Make sure no team member runs index builds or collection drops during the maintenance window. When the move completes, verify collection counts on the new shard before resuming normal writes.

Keep production data safe while engineers check collection state after the move. Apply dynamic data masking so matched fields like emails or card numbers rewrite in results. This lets operators verify unsharded tables without exposing raw personal records.

Check MongoDB commands and documents on the wire

MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB, inline in the MongoDB wire protocol. On every command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13, or hold risky commands for approval. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents in memory, and every verdict is logged. See the open-source code on GitHub.

Frequently asked questions

What does MovePrimaryInProgress mean in MongoDB?

MovePrimaryInProgress means the cluster is moving a database's primary shard to another shard. The database blocks conflicting tasks on unsharded collections until the data transfer finishes.

Is it safe to stop a primary shard move to clear error 319?

No, stopping a primary shard move mid-transfer is unsafe in production. Let the operation finish on its own so cluster metadata stays consistent across all shards.

Which database role should engineers use to inspect collections after error 319?

Assign the built-in read role for the target database during your checks. It allows listCollections, dbStats, and collStats while blocking accidental insert, update, remove, or dropCollection actions.

Short role checks help teams work fast. Simple rules make each review clear. Good logs keep every team safe. Scoped keys stop bad changes early.

The query runs. The emails stay hidden.