How to Fix MongoDB Error 303 (SplitHorizonChange)
You see mongodb error 303 when a replica set changes its split-horizon network config. To fix this error, reconnect your client app so it learns the updated hostnames. MongoDB names this failure code SplitHorizonChange. It belongs to the CloseConnectionError category in the database engine. When a node updates its external or internal network mapping, it closes active client sockets. This drop forces drivers to fetch the fresh topology view right away. What causes mongodb error 303 in your cl
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 303 when a replica set changes its split-horizon network config. To fix this error, reconnect your client app so it learns the updated hostnames.
MongoDB names this failure code SplitHorizonChange. It belongs to the CloseConnectionError category in the database engine. When a node updates its external or internal network mapping, it closes active client sockets. This drop forces drivers to fetch the fresh topology view right away.
What causes mongodb error 303 in your cluster
Replica sets often serve clients inside a private network and outside across the internet. Split-horizon DNS lets nodes share internal hostnames with local peers and external names with remote apps. Each client sees a different address based on where the request starts.
When an admin changes these horizon rules, existing sockets point to stale route mappings. The database engine raises error code 303 and drops affected connections on purpose. Because it sits in the CloseConnectionError group, the server terminates the link to prevent routing mismatches.
Network shifts during cloud migrations or peering updates can also trigger this event. If a load balancer changes how it forwards client traffic, the node sees a different source horizon. The database then resets the socket so the driver can run a fresh handshake.
How to diagnose and fix the failure in production
Start by checking your server logs and network changes around the time of the drop. You do not need to grant broad admin roles to inspect cluster state. MongoDB grants access through role-based authorization on defined resources down to the collection level.
Give your on-call team a limited read role when they inspect database stats. The built-in read role grants actions like find, listCollections, listIndexes, dbStats, and collStats. It leaves out write actions like insert, update, remove, or dropCollection. This keeps production data safe while engineers check node health.
Next, check how your client apps connect to the replica set. Most modern drivers handle a CloseConnectionError by opening a new socket and running a topology check. If your app crashes instead, make sure connection pooling and retry logic are active.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Verify that your DNS records resolve to the right IP addresses from the app subnet. Test the hostname resolution from the exact network where your app runs. If the DNS server returns internal addresses to external clients, fix the zone records.
Preventing split-horizon drops during maintenance
Plan replica set network updates during low traffic windows whenever possible. Rolling out horizon changes one node at a time limits how many sockets drop at once. Wait for each secondary node to settle before you update the primary node.
Keep your driver versions current across all services that talk to the cluster. Updated drivers recover faster when the server sends a CloseConnectionError signal. Also avoid hardcoding IP addresses in your app settings. Use standard DNS seed lists so clients always pick up new horizon hostnames upon reconnecting.
When engineers inspect live collections during an incident, protect sensitive records in query results. Data masking rewrites matched fields like emails, phone numbers, card numbers, and national IDs in results. This lets teams debug connection issues and check sample records safely.
Inspect MongoDB wire traffic in flight
Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.
First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.
Frequently asked questions
Is mongodb error 303 a sign of data corruption?
No, error 303 does not harm your stored data. It is a network signal that forces clients to reconnect after a split-horizon routing change.
Why does the server close the connection on error 303?
SplitHorizonChange belongs to the CloseConnectionError category in MongoDB. Closing the socket forces the client driver to run a fresh handshake and discover the new hostnames.
What database role do I need to check collection stats during troubleshooting?
The built-in read role is enough to run dbStats and collStats on non-system collections. It lets you inspect database state without granting insert, update, or remove privileges.
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