- Error code
- 9
- Code name
FailedToParse- Product
- MongoDB
- Versions
- MongoDB 7.0 and 8.0 (wordings checked against the 8.0 source)
- Category
- Queries & Aggregation
- Last reviewed
- 24 October 2026
On this page
What it means
Error 9 (FailedToParse) means MongoDB could not parse part of a request: an aggregation stage, an expression's arguments or an option such as the write concern is not in the shape the server expects. The message names the part that failed.
Like 2 BadValue, FailedToParse is a family of messages sharing one code. MongoDB raises it while it is still reading the request, before any document is touched, so nothing was written and the fix is always in the request itself. The text varies by the component that rejected it; the forms listed here are common ones taken from MongoDB 8.0's source, not a complete list.
In aggregation, each stage parses its own specification. $lookup, for example, accepts only from, localField, foreignField, let, pipeline and as, and field names are case-sensitive, so localfield is an unknown argument. Expressions such as $convert and window functions in $setWindowFields report missing or unknown arguments the same way. Outside aggregation, the write concern parser uses code 9 for a w value that is not a number, string or object, and for fsync combined with j.
A misspelt option of the command itself (rather than inside a stage) is usually reported by the command parser with a different code, for example BSON field 'find.limitt' is an unknown field. (40415 IDLUnknownField), and an unknown query operator gives 2 BadValue.
Common causes
- A misspelt or wrongly cased argument in a stage, such as localfield or foreignfield in $lookup.
- A required argument left out, such as as in $lookup or to in $convert.
- A write concern built with the wrong types in application code, such as w: true, or fsync and j set together.
- A misspelt window function or argument inside $setWindowFields, such as $summ for $sum.
- A pipeline written for a newer server version, or copied from documentation for another stage, whose options this server does not accept.
Diagnose it
Read-only These mongosh commands only read data, indexes, statistics and server state (find, aggregate without $out or $merge, getIndexes, stats, currentOp, rs.status). They do not change data, users or settings, so they are safe to run first.
Print the pipeline exactly as it is sent
const pipeline = [ /* the pipeline from your code */ ]
print(EJSON.stringify(pipeline, null, 2))The pipeline as JSON. Find the stage or option named in the message and compare its argument names, letter case and value types with the stage's documentation.
Run the stages one at a time
db.orders.aggregate([ { $match: { status: "open" } }, { $limit: 5 } ])
// then add the next stage, and the next, until the error returnsResults until the stage that fails is added. That stage is the one to fix; the message tells you which argument is wrong.
Check the server version when a stage option is rejected
db.version()The server version. Compare it with the version notes on the stage's documentation page when an option you copied is not recognised.
How to fix it
Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.
Correct the stage arguments
Client or network sideUse the exact, case-sensitive argument names and include the required ones. For $lookup with local and foreign fields, all four of from, localField, foreignField and as are needed.
db.orders.aggregate([
{ $lookup: { from: "customers", localField: "customer_id", foreignField: "_id", as: "customer" } }
])Send a valid write concern
Client or network sidew takes a number, "majority" or a tag set name; use j: true for a journaled write and leave out fsync.
db.orders.insertOne(
{ item: "pen", qty: 5 },
{ writeConcern: { w: "majority", j: true, wtimeout: 5000 } }
)Give expressions all their required arguments
Client or network side$convert needs input and to; window functions in $setWindowFields must be spelt exactly as documented.
db.orders.aggregate([
{ $project: { qty: { $convert: { input: "$qty", to: "int", onError: null } } } }
])Examples
A lower-case argument name in $lookup
Not reproduced here: no MongoDB server is installed for this site. The text is built by DocumentSourceLookUp::createFromBson() in MongoDB 8.0's document_source_lookup.cpp from the argument name as written; shown as mongosh prints a server error.
db.orders.aggregate([
{ $lookup: { from: "customers", localfield: "customer_id", foreignField: "_id", as: "customer" } }
])MongoServerError: unknown argument to $lookup: localfield
A boolean write concern
Not reproduced here: no MongoDB server is installed for this site. The text is the one built in MongoDB 8.0's write_concern_idl.cpp (the type name comes from typeName(), which prints bool for a boolean). Whether your driver rejects the value before sending it depends on the driver; this shows the server's reply.
db.orders.insertOne({ item: "pen" }, { writeConcern: { w: true } })MongoServerError: w has to be a number, string, or object; found: bool
A misspelt window function
Not reproduced here: no MongoDB server is installed for this site. The text is built in MongoDB 8.0's window_function_expression.cpp, whose source comment uses this same $summ misspelling as its example; the collection and fields are illustrative.
db.sales.aggregate([
{ $setWindowFields: { sortBy: { day: 1 }, output: {
running: { $summ: "$amount", window: { documents: [ "unbounded", "current" ] } }
} } }
])MongoServerError: Unrecognized window function, $summ
How to prevent it
Keep pipelines in one place in your code with tests that run them against a development server, so a renamed argument fails early. Use your driver's typed options for write concerns instead of building the document by hand.
When copying a stage from documentation, use the page for your server version: newer options are rejected by older servers.
Common questions
What does FailedToParse mean in MongoDB?
The server could not read part of the request, such as a stage specification, an expression's arguments or a write concern. Nothing was executed; correct the part the message names.
Why does $lookup say "unknown argument"?
An argument name is misspelt or wrongly cased. $lookup accepts from, localField, foreignField, let, pipeline and as, and names are case-sensitive.
Is FailedToParse the same as BadValue?
No, but both are generic. FailedToParse (9) is used while parsing a specification; BadValue (2) is used for values that parse but are not acceptable, such as an unknown query operator.
Learn more on CodeWithSQL
Official documentation
Last technically reviewed 24 October 2026; examples and diagnostics run on MongoDB 8.0 documentation and source (error_codes.yml r8.0.0); not run locally. Codes and code names are checked against MongoDB's error_codes.yml (8.0); no MongoDB server was available, so the examples were not run locally.