How to Fix MongoDB Error 28 (PathNotViable)
You trigger mongodb error 28 when an update targets an invalid document path. You fix this PathNotViable error by checking field types before running a write. In the database engine, code 28 maps to the official PathNotViable failure state. This failure happens when a write operation tries to traverse a non-object value. Your query might treat a scalar field or null value like an embedded document. The engine stops the update to protect data integrity across the collection. Root causes of mon
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 trigger mongodb error 28 when an update targets an invalid document path. You fix this PathNotViable error by checking field types before running a write.
In the database engine, code 28 maps to the official PathNotViable failure state. This failure happens when a write operation tries to traverse a non-object value. Your query might treat a scalar field or null value like an embedded document. The engine stops the update to protect data integrity across the collection.
Root causes of mongodb error 28 in document updates
Documents in a collection do not always share the exact same structure. One record might store a nested object at a given field path. Another record in the same collection might store a string or number there. When a broad update runs across both records, the second record fails.
The database engine reads the dotted path step by step during the write. It expects every parent part of the path to be an object or array. If it hits a primitive value instead, the path is not viable. The engine halts the write and returns code 28 to the client app.
Array index confusion also triggers the PathNotViable error in many client apps. A query might try to traverse a field name inside a scalar array element. Because a primitive element has no child fields, the engine rejects the path. Null values at a parent path cause the exact same failure during updates.
How to diagnose and fix PathNotViable safely in production
Fixing a broken document path in production requires careful read checks first. You should not grant wide admin rights just to inspect a failing record. MongoDB grants access through roles that apply to a specific database. A role can grant access down to a collection level of granularity.
Start by assigning the built-in read role to the engineer checking the issue. The read role allows find, listCollections, and listIndexes on non-system collections. It does not allow insert, update, remove, or dropCollection actions on the database. This setup lets your team find bad document shapes without risking accidental writes.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Run a targeted find query to locate records where the parent field is not an object. Filter the collection by checking the data type of the parent field path. During this read check, data masking can rewrite emails or phone numbers in results. Your team sees the broken document structure while sensitive fields stay protected.
Once you find the mismatched records, plan a safe two-step write fix. Only the user or job running the fix needs the readWrite role. The readWrite role adds insert, update, and remove actions to the read permissions. Scope your update filter so it only targets records with the expected parent type.
For records with a scalar or null parent, replace the parent field first. Set the parent field to an empty object before writing the nested child value. You can also add schema validation rules to the collection after the fix. Validation rules stop apps from writing wrong field types in future updates.
Preventing path conflicts across app teams
Schema drift often starts when multiple apps write to the same collection. One service writes a string while another service expects an embedded document. Clear ownership of collection schemas stops this drift before it hits production.
Review your database roles so only the owning service has readWrite access. Other services that only need data should use the read role instead. Limiting write access reduces the chance of conflicting field types in your data.
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 PathNotViable mean in a database log?
PathNotViable is the official name for error code 28 in the database engine. It means an operation tried to step through a field that cannot hold child fields.
Does error 28 corrupt the document being updated?
No, the database engine rejects the invalid update before changing the document. The record keeps its original state until you run a valid write operation.
Which role do I need to inspect documents causing error 28?
You only need the built-in read role on the target database. That role provides the find action to inspect field types without granting write permissions.
Related guides
In this post