How to Fix MongoDB Error 294 (InvalidTopologyType)
You get mongodb error 294 when a command runs on the wrong cluster type. You fix it by matching your command and driver setup to your node topology. In the engine, code 294 maps to the official InvalidTopologyType error name. It stops commands that need a replica set or sharded cluster from running elsewhere. This check protects your data when an app or admin targets the wrong host. Root causes of mongodb error 294 in your cluster MongoDB runs in three main shapes: a single node, a replica s
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 294 when a command runs on the wrong cluster type. You fix it by matching your command and driver setup to your node topology.
In the engine, code 294 maps to the official InvalidTopologyType error name. It stops commands that need a replica set or sharded cluster from running elsewhere. This check protects your data when an app or admin targets the wrong host.
Root causes of mongodb error 294 in your cluster
MongoDB runs in three main shapes: a single node, a replica set, or shards. Each shape supports a specific list of admin and data commands. When you send a shard command to a replica set, the server rejects it. The database then returns code 294 with the InvalidTopologyType label.
Client connection strings also trigger this problem during day-to-day work. An app might expect a full replica set but hit one isolated node instead. This mismatch often happens after a network change or a wrong DNS update. A script might also connect to a data shard instead of the query router.
Cluster setup changes are another common trigger for this error code. If a team member restarts a replica set node as a standalone server, scripts fail. Commands that need cluster state cannot run on a single isolated server. The database engine blocks the call right away to avoid broken state.
How to diagnose and fix InvalidTopologyType safely
First, check which host and port your app or script uses right now. Make sure the target node plays the role your command expects. If you run sharded commands, send them to the router, not to a shard. If you use transactions, check that you connect to a replica set.
You do not need broad admin rights to inspect your cluster shape. MongoDB grants access through roles that allow specific actions on defined resources. A role applies to its home database and works down to the collection level. Even the basic read role lets you run database stats and collection stats. It also allows finding data and listing collections or indexes without write rights. It leaves out data changes like insert, update, remove, or dropping collections.
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 fix privileges small when you update settings or test connections. Only use the readWrite role when an app must change data or indexes. For topology checks, use a read-only role so a bad script cannot change data. If your connection string lists the wrong topology settings, update the client settings first. Then test the fix on a staging cluster before you push to production.
Preventing topology errors during maintenance
Many topology errors start during maintenance windows or fast incident fixes. An engineer might connect to a backend node to check a slow query. If they run a cluster command on that single node, error 294 appears. Clear connection routing rules stop engineers from hitting the wrong node type.
Separate your direct maintenance ports from your normal app traffic paths. Label each database target by its exact role in the cluster. When teams know if a host is a router or shard, mistakes drop. Good role limits also stop unsafe writes if someone picks the wrong host. If query results include sensitive fields, masking rewrites matched emails or card numbers in results.
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 InvalidTopologyType mean in MongoDB?
InvalidTopologyType is the official name for error code 294 in the database engine. It means a command or client setting does not match the current server deployment type.
Can a wrong connection string cause mongodb error 294?
Yes, a bad connection string is a frequent cause of this error. Pointing a sharded cluster client to a standalone node or direct shard triggers it.
Do I need full admin rights to check my MongoDB topology?
No, you do not need write or admin rights to check node state. Built-in read roles let you run stats commands without risking data changes.
Related guides
In this post