How to Fix MongoDB Error 228 (SessionTransferIncomplete)
You see mongodb error 228 when a session transfer between cluster nodes stays incomplete. You fix this error by retrying the operation once the session state finishes moving. In the database engine, code 228 maps to the SessionTransferIncomplete error name. This failure often pops up during chunk migrations, node failovers, or cluster rebalancing work. When a client sends a command mid-transfer, the target node rejects the request. The node waits until it holds the full session record before ru
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 228 when a session transfer between cluster nodes stays incomplete. You fix this error by retrying the operation once the session state finishes moving.
In the database engine, code 228 maps to the SessionTransferIncomplete error name. This failure often pops up during chunk migrations, node failovers, or cluster rebalancing work. When a client sends a command mid-transfer, the target node rejects the request. The node waits until it holds the full session record before running new writes.
Root causes of mongodb error 228 in a cluster
Database clusters track active client sessions to keep multi-step writes safe and ordered. When data moves from one shard or node to another, session records move too. If a network delay slows this move, the receiving node lacks the full state. A client request that lands during this brief gap triggers code 228 right away.
Heavy write loads make this error show up more often during peak traffic hours. Large transactions hold session state open longer while nodes try to shift data around. Slow disk reads or high network latency between cluster members also stretch the transfer time. Client drivers might also hit this issue if retry logic is turned off.
Bad connection pool settings can push too many requests to a busy shard. When a primary node steps down, the new primary must load recent session data. Until that load ends, any active session request fails with the incomplete transfer message. Knowing why the transfer stalled helps your team pick the right fix fast.
How to diagnose and fix session transfer errors safely
Start your check by reading the database logs on both the source and target nodes. Look for stalled migrations, network drops, or election events right before the error timestamp. You do not need full admin rights to check basic cluster health metrics. MongoDB grants access through role-based rules that apply to a specific database.
A role grants permission to run sets of actions on defined database resources. It can grant access down to a collection level of detail for your team. For diagnostic checks, give responders the built-in read role on the affected database. The read role grants read access to all non-system collections in that database.
Session Binding to Device + MongoDB Authentication & Authorization: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
It allows safe actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It does not allow insert, update, remove, or dropCollection actions during an incident. Avoid handing out the readWrite role unless an engineer must change data to recover. The readWrite role adds insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection actions.
Note that cloud database users have different built-in roles than self-hosted database users. Both user types still build their permissions from the same set of privilege actions. Once you confirm a stalled transfer, let the background move finish before pushing heavy writes. Update your app client to retry failed session operations after a short wait.
Preventing future session transfer failures in production
You can cut down on code 228 errors by keeping transactions small and fast. Short operations finish before shard balancing or routine maintenance needs to move session state. Schedule heavy data loads and index builds during quiet hours with low user traffic. Keep network links between cluster nodes fast and free of packet drops.
Review your database access rules so automated scripts cannot overload a single shard. Limit write permissions to the exact collections each service needs for its daily work. When engineers inspect live production data, mask sensitive fields like emails and phone numbers. Masking rewrites matched fields in query results, such as card numbers or national IDs.
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 SessionTransferIncomplete mean in MongoDB?
SessionTransferIncomplete is the official name for error code 228 in the database engine. It means a node received a session request before the session state finished transferring.
Can a retry fix mongodb error 228 for client apps?
Yes, most session transfer gaps last only a few seconds during normal cluster shifts. Retrying the failed read or write after a brief pause usually succeeds right away.
Which role should engineers use to inspect error 228?
Assign the built-in read role so engineers can run dbStats and collStats safely. This role blocks data changes like update or dropCollection while they check the cluster.
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.
Related guides
In this post