How to Fix MongoDB Error 97 (NoProjectionFound)
You see mongodb error 97 when the database engine expects a field projection that is missing. You fix this NoProjectionFound error by supplying a valid projection document in your query or pipeline stage. Database queries often request specific fields from a collection. When an operation requires a projection definition and receives none, the server stops the request. Understanding how the engine reads your query structure helps your team resolve this failure fast. Root causes of mongodb erro
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 97 when the database engine expects a field projection that is missing. You fix this NoProjectionFound error by supplying a valid projection document in your query or pipeline stage.
Database queries often request specific fields from a collection. When an operation requires a projection definition and receives none, the server stops the request. Understanding how the engine reads your query structure helps your team resolve this failure fast.
Root causes of mongodb error 97 in database queries
In the official server spec, code 97 maps to the internal name NoProjectionFound. The database triggers this code when an internal query stage looks for a projection map and finds nothing. This happens most often during complex read operations or custom aggregation pipelines.
Client drivers and object mappers build query documents before sending them over the network. If a client app passes an empty or null value where the server expects a projection object, the parser rejects the command. You might also see this if a custom query builder strips out projection fields before execution.
Distributed clusters and sharded setups also pass projection specs between nodes. When a router node forwards a read request to a shard, both nodes must agree on the query shape. If a version mismatch or malformed command drops the projection part, the shard returns code 97.
Sometimes, teams mistake this failure for a permission problem. MongoDB grants access through role-based rules that apply to a database down to the collection level. Still, built-in roles control actions like find or update, not individual field projections.
How to diagnose and fix NoProjectionFound in production
Start by finding the exact query that triggered the failure in your server logs. Check the app trace to see which service or user session sent the broken read command. Look closely at how that code builds the projection part of the find or aggregation call.
When you inspect the production database, use a least-privilege role. The built-in read role gives access to non-system collections through actions like find, listCollections, and listIndexes. It does not allow insert, update, remove, or dropCollection actions, which keeps your data safe during checks.
Never grant write privileges just to debug a read projection failure. The readWrite role includes actions that modify data, such as insert, update, remove, and dropIndex. Keeping your debugging session limited to read actions prevents accidental changes to live collections.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Once you locate the broken query in your app code, check the projection argument. Make sure the app passes a valid document that explicitly includes or excludes the needed fields. If the operation does not need field filtering, remove the empty projection parameter so the driver sends a clean request.
Test the updated query in a staging database before you deploy it to production. Verify that the client driver version matches your database server requirements. If your team queries sensitive collections during testing, remember that data masking rewrites matched fields like emails, phone numbers, card numbers, or national IDs in results.
Preventing projection errors in team workflows
Many query errors happen when engineers write ad-hoc commands during an incident. Typing complex find queries by hand makes it easy to leave out a required document bracket or field name. Standardizing how your team runs read queries cuts down on syntax mistakes.
Set up automated tests that check query shapes before code merges into your main branch. Have your test suite run key read and aggregation paths against a real database instance. Catching a missing projection in test runs keeps code 97 out of your production logs.
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
What does MongoDB error code 97 mean?
Error code 97 is named NoProjectionFound in the official database error list. It means an operation needed a projection spec to choose which fields to return, but none was provided.
Does a missing database role cause NoProjectionFound?
No, database roles grant privileges down to the collection level for actions like find or insert. Code 97 comes from a missing or broken projection structure in the query itself, not from role permissions.
Which role should I use to debug read queries safely?
Use the built-in read role on the target database when checking query behavior. It allows read actions like find, collStats, and listIndexes without permitting data changes like update or remove.
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.
Teams test new role rules in staging first. Clear owner lists speed up each audit. Small role scopes cut down on risk. Regular log checks catch drift right away.
Related guides
In this post