How to Fix MongoDB Error 306 (ReadThroughCacheLookupCanceled)
You get mongodb error 306 when the server stops an internal read-through cache lookup early. To fix it, retry the stopped read query and check your cluster for node stepdowns. MongoDB names this failure code ReadThroughCacheLookupCanceled in its official server error list. The database engine marks this code as an internal only category event. That means the storage or routing layer uses it inside the cluster. Client apps rarely see it unless an internal task drops mid-flight. What causes mon
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 306 when the server stops an internal read-through cache lookup early. To fix it, retry the stopped read query and check your cluster for node stepdowns.
MongoDB names this failure code ReadThroughCacheLookupCanceled in its official server error list. The database engine marks this code as an internal only category event. That means the storage or routing layer uses it inside the cluster. Client apps rarely see it unless an internal task drops mid-flight.
What causes mongodb error 306 in your cluster
A read-through cache sits between fast memory and slower disk or catalog records. When a node needs metadata or user roles, it checks the local cache first. If the cache misses, the node starts a background read from the backing store.
Sometimes another thread cancels that lookup before the backing store answers. A primary node stepdown during an election often triggers this sudden stop. A client timeout or an admin kill command can also stop the wait.
When the lookup stops, the server throws the ReadThroughCacheLookupCanceled code to clean up state. High load on the backing store makes these cache misses take longer. Longer waits raise the chance that a timeout cancels the pending lookup.
How to diagnose and fix the failure in production
Start by checking your server logs around the exact time of the error. Look for replica set elections, network drops, or slow disk reads on the primary. If a node stepped down, the cache lookup stopped to protect data state.
Next, check if your app retries failed reads after a brief pause. Most transient internal errors clear up on the very next read attempt. If the error repeats, inspect the backing collection for locks or slow queries.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Keep your database privileges tight while your team checks these production logs. MongoDB grants access through roles that define actions on specific resources. A role applies to its home database and can control access down to one collection.
Give your responders the built-in read role when they inspect affected data. The read role lets them run find, listCollections, listIndexes, dbStats, and collStats safely. It leaves out write actions like insert, update, remove, and dropCollection.
Never hand out the readWrite role just to debug a cache lookup error. That role adds power to change data, create indexes, or drop collections by mistake. You should also mask sensitive fields like emails, phone numbers, and card numbers in query results. Data masking rewrites matched fields in results so responders fix bugs without exposing private records.
How to prevent cache lookup cancellations
You can lower the rate of canceled lookups by keeping queries fast. Set clear time limits on app queries so stuck reads do not pile up. Make sure your replica set nodes have stable network links to avoid false elections.
Watch your disk latency and memory pressure during peak traffic hours. When nodes have enough memory, the cache hits more often and skips slow lookups. Review your role definitions often so every user and service holds minimal rights.
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 ReadThroughCacheLookupCanceled mean in MongoDB?
It means the database engine stopped an internal cache read before it finished. MongoDB assigns error code 306 to this internal event when a thread aborts the wait.
Does mongodb error 306 damage stored data?
No, this error only stops an in-flight read operation inside the cache layer. Your stored documents remain safe on disk, and a simple query retry usually works.
Which role should engineers use to inspect collections after error 306?
Assign the built-in read role on the target database for safe debugging. It allows read stats and find queries while blocking all data changes and collection drops.
Related guides
In this post