How to Fix MongoDB Error 31 (RoleNotFound)
You see mongodb error 31 when a command names a role that does not exist. You fix this RoleNotFound error by checking the target database and role spelling. MongoDB uses role-based rules to control what users can do on a cluster. Each role grants specific actions on set resources down to the collection level. If you assign or edit a missing role, the database engine stops the action. It returns code 31 with the RoleNotFound label right away. What causes mongodb error 31 in your database The
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 31 when a command names a role that does not exist. You fix this RoleNotFound error by checking the target database and role spelling.
MongoDB uses role-based rules to control what users can do on a cluster. Each role grants specific actions on set resources down to the collection level. If you assign or edit a missing role, the database engine stops the action. It returns code 31 with the RoleNotFound label right away.
What causes mongodb error 31 in your database
The most common cause for mongodb error 31 is a simple database scope mismatch. A role applies to the exact database where your team defined it. If a script looks for a custom role in the wrong database, it fails. Even one wrong letter in the role name triggers the RoleNotFound error.
Platform differences also cause this problem when teams move workloads. MongoDB Atlas database users have different built-in roles than self-hosted deployment users. Both setups build roles from the same set of privilege actions. Still, a role name from a self-hosted server might not exist in Atlas.
Deployment scripts can also fail due to bad execution order. An automation job might create a user before it builds the custom role. When the user step runs, the database cannot find the role yet. A teammate might also drop an old custom role while scripts still use it.
How to diagnose and fix the RoleNotFound error safely
Start by checking the exact database where your command ran. Switch to that database and list all custom and built-in roles. Check the spelling and letter case of the role in your failed script. Role names in MongoDB must match the stored role name letter for letter.
If the role is missing, compare the needed access against built-in options first. The read role gives read access to all non-system collections in its database. It also covers the system.js collection through actions like find and listCollections. It includes listIndexes, dbStats, collStats, and changeStream, but blocks insert, update, remove, or dropCollection.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
When an app must change data, look at the readWrite role instead. The readWrite role includes everything in read plus the power to change data. Its actions cover insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection. Using these standard roles prevents missing custom role errors across your clusters.
Never fix a RoleNotFound error by giving out broad admin rights in production. That quick shortcut leaves your production data open to bad writes or drops. Instead, create the missing custom role on the right database with minimal actions. Grant access down to the collection level so the user only touches needed data.
How to prevent role errors across your clusters
You can stop role errors by keeping role definitions in version control. Make sure your setup tools create custom roles before they create database users. Test these scripts in a staging setup that matches your production hosting type. This catches differences between Atlas roles and self-hosted roles before code goes live.
Review your database roles often to keep permissions clean and simple. When apps only need standard access, stick to the built-in read or readWrite roles. Keep custom roles small and tie them to clear database names. Good role hygiene stops error 31 and keeps your production data safe.
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 MongoDB error code 31 mean?
Error code 31 means RoleNotFound in the MongoDB database engine. It happens when a command points to a role that does not exist there.
Why does my role work on a self-hosted server but fail in Atlas?
MongoDB Atlas database users have different built-in roles than self-hosted deployment users. You must update your scripts to use role names that match your hosting type.
Should I use a custom role or the built-in read role?
Use the built-in read role if the user needs read access to non-system collections. Build a custom role only when you must limit actions to specific collections.
Related guides
In this post