How to Fix MongoDB Error 13388 (StaleConfig)

Published
Length
3 min read

Luis Felipe Dias

All posts

A sharded cluster triggers mongodb error 13388 when a query router uses outdated chunk metadata. You can fix this StaleConfig failure by refreshing the router cache and retrying the request. In a sharded database, data lives in chunks across many shard nodes. Query routers keep a local map of where each data chunk sits. When the cluster moves chunks between shards, the local router map can fall behind. If a router sends a query using old map data, the shard rejects the request. Root causes of

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.

A sharded cluster triggers mongodb error 13388 when a query router uses outdated chunk metadata. You can fix this StaleConfig failure by refreshing the router cache and retrying the request.

In a sharded database, data lives in chunks across many shard nodes. Query routers keep a local map of where each data chunk sits. When the cluster moves chunks between shards, the local router map can fall behind. If a router sends a query using old map data, the shard rejects the request.

Root causes of mongodb error 13388 in sharded clusters

In the database engine, code 13388 maps to the StaleConfig error name. It belongs to the StaleShardVersionError and NeedRetargettingError categories inside the database engine. These categories mean a shard saw an older version number than its current metadata.

When the balancer moves a chunk to a new shard, the metadata version goes up. The config servers record this new version right away. Still, other query routers might not know about the move yet. A router sends a read or write to the old shard with the old version. The shard checks the version, sees the mismatch, and returns error 13388.

Usually, the query router catches this error, refreshes its cache, and retries the work. The app only sees the failure when the retry loop breaks or times out. Network drops between routers and config servers often block metadata refreshes. Long transactions can also hold onto an old shard version past a chunk move. In rare cases, a stuck balancer lock leaves the cluster map in a split state.

How to diagnose and fix StaleConfig safely in production

Start by checking the logs on both the query router and the target shard. Look for network timeouts between the query routers and the config server replica set. If a router cannot reach the config servers, it cannot pull the new chunk map.

Check if a collection was dropped and remade with the same name right away. That pattern often leaves routers holding old collection metadata across the cluster. Wait a moment between dropping and creating sharded collections so routers can catch up. If one router stays stuck, run a cache refresh command on that router node.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Do not give engineers broad admin roles just to inspect shard status during an incident. The database grants access through roles that define allowed actions on specific resources. A role applies to its home database and can limit access to one collection. Built-in roles on cloud clusters differ from self-hosted ones, yet use the same actions.

For safe checks, assign the read role on the target database to your responders. The read role grants read access to all non-system collections in that database. It allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream for safe checks. It leaves out insert, update, remove, and dropCollection so responders cannot change live data.

Reserve the readWrite role for controlled fix steps that must change state. The readWrite role includes everything in read plus actions that modify data and indexes. Those actions cover insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection.

Preventing repeat metadata routing failures

You can lower the rate of StaleConfig errors by tuning how your app runs queries. Keep transactions short so they finish before the balancer moves a chunk across shards. Make sure your client driver stays up to date and supports retryable reads and writes.

Schedule heavy collection drops or shard key changes during low traffic windows. Check config server health every day so metadata changes spread fast to all routers. When you pair clean routing with scoped roles, your team can fix shard errors safely.

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 StaleConfig mean in a sharded cluster?

StaleConfig means a query router sent an operation using an outdated shard version number. The receiving shard blocks the request and asks the router to refresh its metadata.

Why did error 13388 reach my app instead of retrying?

Query routers retry most StaleConfig errors behind the scenes. The error reaches your app when retries run out, a transaction runs, or config servers drop offline.

Which role should engineers use to check collection stats during this error?

Assign the built-in read role on the affected database. It allows dbStats, collStats, find, and listIndexes without allowing insert, update, remove, or dropCollection.

The query runs. The emails stay hidden.