How to Fix MongoDB Error 465 (PlacementHistoryInitializationInProgress)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 465 when a sharded cluster is still building its placement history. To fix it, wait for the setup task to finish and retry your query. The database engine maps this code to the official name PlacementHistoryInitializationInProgress. This state happens when a cluster updates its internal map of shard data locations. Operations that rely on historic data placement pause until the system finishes this startup task. Most apps only need a brief pause and a retry loop to clear t

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 465 when a sharded cluster is still building its placement history. To fix it, wait for the setup task to finish and retry your query.

The database engine maps this code to the official name PlacementHistoryInitializationInProgress. This state happens when a cluster updates its internal map of shard data locations. Operations that rely on historic data placement pause until the system finishes this startup task. Most apps only need a brief pause and a retry loop to clear the fault.

Root causes of mongodb error 465 in sharded clusters

A sharded cluster keeps a timeline of where collections and chunks live over time. This placement history lets the database route point-in-time reads to the right shard nodes. When you start a new cluster or upgrade one, the config servers build this metadata. If a client asks for placement history before the task finishes, the server rejects it.

Network drops between config servers and query routers can also slow down this background task. Heavy write loads on the config database make the initialization take much longer than normal. Large clusters with thousands of collections need more time to scan and record every shard. Until the config primary writes the full baseline, queries that need history will fail.

How to diagnose and fix the failure in production

Start by checking your config server logs to see if the history task is running. Look for log entries that show progress or blocks on the config database nodes. You do not need full admin rights to check basic database and collection stats. MongoDB grants access through roles that apply to a single database down to one collection.

Give your on-call engineers a read role instead of full write access during diagnosis. The read role lets a user run stats and list collections without changing any data. It blocks actions that insert, update, remove, or drop collections by mistake during an incident. Once you confirm the config servers are healthy, let the background job finish its work.

Do not restart the config servers while they build the placement history. A restart forces the initialization task to start over or wait for a new election. Instead, lower the rate of metadata changes like chunk splits or collection drops. When the background job completes, your client retry logic will succeed without manual fixes.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

How to prevent placement history errors during maintenance

Plan cluster upgrades and shard additions during low-traffic windows to reduce metadata lock contention. Make sure your app drivers use retry logic with backoff for transient cluster errors. Separate your day-to-day read roles from the write roles that create or drop collections. Limiting who can run collection changes keeps config server load steady during busy hours.

When engineers inspect production data to debug shard routing, protect sensitive fields in query outputs. Data masking rewrites matched fields like emails, phone numbers, card numbers, and national IDs. This lets your team check shard placement and query behavior safely during an active outage. Clear role rules and safe retry loops keep your cluster stable when metadata tasks run.

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 PlacementHistoryInitializationInProgress mean in MongoDB?

It means the sharded cluster is still building its internal record of data locations. Commands that need this history must wait until the config servers finish the task.

Do I need write permissions to check why error 465 is happening?

No, you can inspect database and collection stats using the built-in read role. This role allows read actions like listing collections and checking stats without allowing data changes.

Should I restart my shard routers when I see error code 465?

No, restarting routers or config servers will not speed up placement history setup. Wait for the config servers to finish the background job and retry the failed request.

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.