Postconditions: what we check

• connect · connection-failure

  error
  WhenNetwork error, authentication failure, or server selection timeout
  ThrowsMongoNetworkError, MongoServerSelectionError, MongoNetworkTimeoutError, or MongoError
  Required handlingCaller MUST catch connection errors and handle them separately from query errors. Implement retry logic with exponential backoff for transient connection issues. Log connection errors for operations monitoring.
  costcriticalin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• find · query-failure

  error
  WhenNetwork error, timeout, or invalid query syntax
  ThrowsMongoServerError, MongoNetworkError, or MongoError
  Required handlingCaller MUST catch query errors. Network errors (MongoNetworkError) may be transient and can be retried. Invalid query errors (MongoServerError) should not be retried.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• findOne · query-failure

  error
  WhenNetwork error, timeout, or invalid query
  ThrowsMongoServerError, MongoNetworkError, or MongoError
  Required handlingCaller MUST catch query errors. Returns null if no document matches (not an error). Network errors may be transient and retriable.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• insertOne · duplicate-key

  error
  WhenDocument violates unique index constraint
  ThrowsMongoServerError with error.code === 11000
  Required handlingCaller MUST catch duplicate key errors (code 11000) and handle gracefully. Extract conflicting field from error message. DO NOT retry without changing the unique field value.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• insertMany · bulk-write-failure

  error
  WhenOne or more documents failed to insert
  ThrowsMongoBulkWriteError with details of failed operations
  Required handlingCaller MUST catch bulk write errors. Check error.result to see which documents succeeded and which failed. Handle partial success scenarios appropriately.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• updateOne · update-failure

  error
  WhenNetwork error, invalid update operation, or write concern failure
  ThrowsMongoServerError, MongoWriteConcernError, or MongoError
  Required handlingCaller MUST catch update errors. Network errors may be transient. Invalid update operators (MongoServerError) should not be retried.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• updateMany · bulk-update-failure

  error
  WhenUpdate operation failed or write concern not satisfied
  ThrowsMongoServerError, MongoWriteConcernError, or MongoError
  Required handlingCaller MUST catch bulk update errors. Check result.modifiedCount to verify how many documents were updated. Implement retry logic for transient failures.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• deleteOne · delete-failure

  error
  WhenNetwork error or write concern failure
  ThrowsMongoServerError, MongoWriteConcernError, or MongoError
  Required handlingCaller MUST catch delete errors. Deleting non-existent document is NOT an error (deletedCount = 0). Network errors may be transient and retriable.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• deleteMany · bulk-delete-failure

  error
  WhenDelete operation failed or write concern not satisfied
  ThrowsMongoServerError, MongoWriteConcernError, or MongoError
  Required handlingCaller MUST catch bulk delete errors. Check result.deletedCount to verify how many documents were deleted. Implement retry logic for transient failures.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• aggregate · aggregation-failure

  error
  WhenInvalid pipeline stage, network error, or timeout
  ThrowsMongoServerError, MongoNetworkError, or MongoError
  Required handlingCaller MUST catch aggregation errors. Pipeline syntax errors (MongoServerError) should not be retried. Network errors may be transient and retriable.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• countDocuments · count-failure

  error
  WhenNetwork error, timeout, or invalid filter
  ThrowsMongoServerError, MongoNetworkError, or MongoError
  Required handlingCaller MUST catch count errors. Network errors may be transient. Invalid filters should not be retried.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• createIndex · index-creation-failure

  error
  WhenInvalid index options, duplicate index name, or insufficient permissions
  ThrowsMongoServerError or MongoError
  Required handlingCaller MUST catch index creation errors. Index with same name but different options will fail. Check if index already exists before creating.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• drop · drop-failure

  error
  WhenCollection does not exist, insufficient permissions, or network error
  ThrowsMongoServerError or MongoError
  Required handlingCaller MUST catch drop errors. Dropping non-existent collection throws error. Use dropCollection with ifExists option to avoid errors.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• collection · collection-access-failure

  error
  WhenInvalid collection name or database not connected
  ThrowsMongoError
  Required handlingCaller MUST catch collection access errors. Ensure database connection is established before accessing collections. Validate collection names before use.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• bulkWrite · bulk-write-failure

  error
  WhenOne or more operations failed
  ThrowsMongoBulkWriteError with details of failed operations
  Required handlingCaller MUST catch bulk write errors. Check error.result for success/failure details of each operation. Handle partial success appropriately.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• findOneAndUpdate · findoneandupdate-null-not-found

  error
  WhenNo document matches the filter (default behavior without upsert)
  ThrowsReturns null — does NOT throw
  Required handlingCaller MUST check for null return. Treating null as success is the most common production bug with findOneAndUpdate. When the document is expected to exist (e.g., optimistic lock update), null return means another process deleted it. Use returnDocument: 'after' and check result before proceeding. If existence is mandatory, use findOneAndUpdateOrThrow pattern or assert null explicitly.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[3][4]
• findOneAndUpdate · findoneandupdate-write-concern-error

  error
  WhenWrite concern requirements not met (replica set not acknowledging)
  ThrowsMongoWriteConcernError
  Required handlingCaller MUST catch MongoWriteConcernError. The write may or may not have been applied — write concern error means acknowledgment failed, not necessarily that the write failed. Implement retry with idempotency checks.
  costhighin proddelayed failureusers seelost datavisibilitysilent
  Sources[2][5]
• findOneAndUpdate · findoneandupdate-duplicate-key-upsert

  error
  Whenupsert:true and unique index conflict when inserting new document
  ThrowsMongoServerError with error.code === 11000
  Required handlingCaller MUST catch MongoServerError with code 11000 when using upsert:true. This happens in high-concurrency scenarios when two requests both try to upsert the same document simultaneously. The second upsert fails with duplicate key error.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• findOneAndDelete · findoneanddelete-null-not-found

  error
  WhenNo document matches the filter
  ThrowsReturns null — does NOT throw
  Required handlingCaller MUST check for null return. A null return means no document was deleted. In queue/dequeue patterns (popping tasks from a queue), null means the queue is empty — must be handled explicitly. Do not attempt to access properties of the null result.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[2][4]
• findOneAndDelete · findoneanddelete-network-error

  error
  WhenNetwork error or server unavailable during delete
  ThrowsMongoNetworkError or MongoServerSelectionError
  Required handlingCaller MUST catch network errors. After a network error during findOneAndDelete, the delete state is unknown — the document may or may not have been deleted. Do not retry without checking current state first.
  costhighin proddelayed failureusers seesecurity breachvisibilitysilent
  Sources[2]
• findOneAndReplace · findoneandreplace-null-not-found

  error
  WhenNo document matches the filter (and upsert is not set)
  ThrowsReturns null — does NOT throw
  Required handlingCaller MUST check for null return. Null means no document was found and replaced. Unlike updateOne which returns matchedCount:0, findOneAndReplace returns null. Check result before proceeding with any logic that depends on the replaced document.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[2]
• findOneAndReplace · findoneandreplace-validation-error

  error
  WhenReplacement document violates schema validation rules
  ThrowsMongoServerError with codeName: 'DocumentValidationFailure'
  Required handlingCaller MUST catch MongoServerError. Unlike findOneAndUpdate (which applies an update operator), findOneAndReplace replaces the entire document — schema validation applies to the full replacement document. Check schema validation rules before replacing.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[7]
• withTransaction · withtransaction-transient-error-not-retried-externally

  error
  WhenNon-transient error thrown by callback operation
  ThrowsMongoServerError, MongoNetworkError, or MongoError — propagated from callback
  Required handlingCaller MUST wrap withTransaction in try-catch. withTransaction automatically retries TransientTransactionError and UnknownTransactionCommitResult. Any other error propagates to caller. Do NOT wrap callback operations in their own try-catch unless you re-throw — swallowing errors inside the callback prevents withTransaction's retry logic from firing.
  costcriticalin prodsilent failureusers seelost datavisibilitysilent
  Sources[8][9]
• withTransaction · withtransaction-write-conflict

  error
  WhenTwo concurrent transactions modify the same document (WriteConflict)
  ThrowsMongoServerError with code 112 (WriteConflict) — labeled TransientTransactionError
  Required handlingwithTransaction automatically retries WriteConflict errors when labeled TransientTransactionError. However if the total elapsed time exceeds 120 seconds, the error propagates. Caller MUST handle the propagated error. Keep transactions short to minimize conflict window.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[8][9]
• withTransaction · withtransaction-session-required

  error
  WhenAll operations inside callback must use the session parameter
  ThrowsOperations without session bypass transaction — no error thrown, silent data corruption
  Required handlingCRITICAL: Every MongoDB operation inside the withTransaction callback MUST pass the session object (e.g., collection.insertOne(doc, { session })). Operations without the session parameter run outside the transaction — they commit immediately regardless of whether the overall transaction commits or aborts. This is a logic error, not an exception.
  costcriticalin prodsilent failureusers seelost datavisibilitysilent
  Sources[9][8]
• watch · watch-error-event-not-thrown

  error
  WhenNetwork disconnection, resume token expiration, or oplog rollover
  ThrowsEmits 'error' event on the ChangeStream — does NOT throw
  Required handlingCaller MUST attach an 'error' event listener to the ChangeStream before using it. Without an error listener, unhandled 'error' events crash the Node.js process. The ChangeStream attempts automatic resume after transient errors (MongoNetworkError) but emits 'error' for unresumable failures (e.g., oplog rolled over past resume token). Pattern: changeStream.on('error', (err) => { /* log and reconnect */ });
  costcriticalin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[10][2]
• watch · watch-resume-token-expired

  error
  WhenResume token references a position that has been rolled off the oplog
  ThrowsEmits 'error' event with MongoServerError — ChangeStream cannot resume
  Required handlingCaller MUST handle the 'error' event and implement a full restart strategy (not just resume) when the resume token has expired. The ChangeStream cannot recover from oplog rollover — the stream must be re-opened from the current oplog position, and the application must re-sync any missed changes via a full collection scan or checkpoint.
  costhighin proddelayed failureusers seelost datavisibilitysilent
  Sources[11]
• replaceOne · replaceone-validation-failure

  error
  WhenReplacement document fails server-side schema validation
  ThrowsMongoServerError with codeName: 'DocumentValidationFailure'
  Required handlingCaller MUST catch MongoServerError. replaceOne replaces the entire document, so all required fields must be present in the replacement. Schema validation errors are not thrown by updateOne for partial updates but ARE thrown by replaceOne for missing required fields in the replacement.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[7][2]
• replaceOne · replaceone-network-error

  error
  WhenNetwork error during replacement
  ThrowsMongoNetworkError or MongoServerSelectionError
  Required handlingCaller MUST catch network errors. replaceOne is NOT idempotent if the replacement document contains different data — retrying without checking whether the replacement was applied may replace data that was already replaced correctly.
  costmediumin proddelayed failureusers seelost datavisibilitysilent
  Sources[2]
• close · close-not-called-resource-leak

  warning
  WhenMongoClient.close() never called before process exit
  ThrowsDoes not throw — process exits with open connections
  Required handlingCaller MUST call client.close() in a finally block or process shutdown handler. Open connections at exit cause connection pool exhaustion on the MongoDB server (connections are not returned to the pool on abrupt exit). Pattern: process.on('SIGTERM', async () => { await client.close(); process.exit(0); }); Or: try { await operations(); } finally { await client.close(); }
  costmediumin proddelayed failureusers seeservice unavailablevisibilityvisible
  Sources[2][12]
• close · close-operations-in-flight

  error
  Whenclose() called while operations are still in progress
  ThrowsIn-progress operations throw MongoClientClosedError
  Required handlingCaller MUST ensure all in-progress operations complete (or are cancelled) before calling close(). Use await to drain operation promises before calling close(). In graceful shutdown: stop accepting new requests, wait for current requests to complete, then close.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13]
• dropIndex · dropindex-not-found

  error
  WhenSpecified index does not exist
  ThrowsMongoServerError with codeName: 'IndexNotFound' or code 27
  Required handlingCaller MUST catch MongoServerError and check for IndexNotFound. Unlike dropIndexes() (which succeeds even with no indexes), dropIndex() throws when the named index does not exist. Use createIndex first to ensure existence, or catch and ignore IndexNotFound specifically.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][14]
• createCollection · createcollection-namespace-exists

  error
  WhenA collection with the same name already exists in the database. This is the most common error for createCollection() in migration/startup code. If the collection was created by a previous migration run, a second call throws instead of being idempotent.
  ThrowsMongoServerError with code 48 (NamespaceExists) and codeName: 'NamespaceExists'. The error message is: "Collection <dbname>.<name> already exists."
  Required handlingCaller MUST catch MongoServerError code 48 and handle idempotently. Two patterns: Option 1 (recommended): Use Db.listCollections() to check first, or catch and ignore: try { await db.createCollection('users', { validator: { $jsonSchema: { ... } } }); } catch (error) { if (error instanceof MongoServerError && error.code === 48) { // Collection already exists — safe to ignore in idempotent migrations } else { throw error; } } Option 2: Pass { checkExistingFieldNames: false } if using schema validation and collection may already exist. CRITICAL: Do NOT ignore all MongoServerError — code 48 is idempotent-safe, but other codes (schema validation syntax errors, permission denied) must propagate.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15][16][17]
• createCollection · createcollection-validation-schema-error

  error
  WhenThe validator option specifies an invalid JSON schema — syntax errors, unknown keywords, or invalid $jsonSchema values. Also thrown when schema contains Queryable Encryption (FLE2) fields but the MongoDB server version is below the minimum required for encrypted collections (< 7.0 wire protocol version 21).
  ThrowsMongoServerError with codeName: 'BadValue' for invalid schema syntax. MongoCompatibilityError (extends MongoDriverError) with message: "Driver support of Queryable Encryption is incompatible with server..." when FLE2 encrypted fields are used against an older server. Confirmed from create_collection.js: 'throw new MongoCompatibilityError(INVALID_QE_VERSION)'.
  Required handlingCaller MUST catch both MongoServerError (schema syntax) and MongoCompatibilityError (FLE2 version mismatch) in startup/migration paths. A schema validation error in startup silently skips collection configuration in some frameworks (Next.js swallows module-load errors) — always log and halt. try { await db.createCollection('products', { validator: { $jsonSchema: { bsonType: 'object', required: ['name'] } } }); } catch (error) { if (error instanceof MongoCompatibilityError) { console.error('Server too old for encrypted collections:', error.message); process.exit(1); } if (error instanceof MongoServerError && error.code === 48) { // Already exists — acceptable in idempotent migrations } else if (error instanceof MongoServerError) { console.error('Invalid collection config:', error.message); throw error; } }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17][16]
• distinct · distinct-no-try-catch

  error
  Whendistinct() is called without try-catch. If the collection or database is unavailable (network failure, server selection timeout), or if the key field path is invalid according to server-side rules, the Promise rejects. Common in API endpoints that return facet values for UI dropdowns — an uncaught error returns a 500 instead of an empty facet list.
  ThrowsMongoServerError (invalid field path or server-side validation failure), MongoNetworkError (network failure — connection dropped), MongoServerSelectionError (no server available within serverSelectionTimeoutMS), MongoError (catch-all base class for all MongoDB errors). Returns empty array [] when no documents match — does NOT throw.
  Required handlingCaller MUST wrap distinct() in try-catch. Returning [] on error is often acceptable for non-critical facet endpoints: try { const categories = await collection.distinct('category', { status: 'active' }); return categories; } catch (error) { if (error instanceof MongoNetworkError) { // Transient — retry or return stale cached values throw error; } if (error instanceof MongoServerError) { // Field path invalid or server error — log and return empty console.error('distinct failed:', error.message, error.code); return []; } throw error; } Note: distinct() returns [] when the query matches no documents. An empty result is NOT an error and must not be confused with a failed query.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18][19]
• createIndexes · createindexes-options-conflict

  error
  WhenAn index with the same key spec already exists but with different options (e.g., same fields but different unique/sparse/collation settings). MongoDB rejects index creation when the name or key spec conflicts with an existing index definition. Common in deployments where index options are changed between app versions.
  ThrowsMongoServerError with code 85 (IndexOptionsConflict) when an existing index has the same name but different options, or code 86 (IndexKeySpecsConflict) when the same key spec exists under a different index name. Neither is idempotent-safe. Confirmed from MongoDB server error codes reference.
  Required handlingCaller MUST catch MongoServerError and check the code. createIndexes() is idempotent for identical index definitions (same key + same options), but throws on conflicting definitions. In migration code: try { await collection.createIndexes([ { key: { email: 1 }, name: 'email_unique', unique: true }, { key: { createdAt: -1 }, name: 'created_at_desc', expireAfterSeconds: 86400 } ]); } catch (error) { if (error instanceof MongoServerError && (error.code === 85 || error.code === 86)) { // Index conflict — need to drop and recreate, or update migration script console.error('Index conflict — cannot create:', error.message); throw error; } throw error; } To safely update an existing index, call dropIndex() with the conflicting name before calling createIndexes() in the same migration transaction.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15][20][21]
• dropIndexes · dropindexes-namespace-not-found

  error
  WhendropIndexes() is called on a collection that does not exist in the database. This differs from dropIndex() behavior — while both operate on indexes, dropIndexes() on a non-existent collection throws NamespaceNotFound. Common in migration scripts that attempt to clean up indexes before the collection has been created.
  ThrowsMongoServerError with code 26 (NamespaceNotFound, defined in MONGODB_ERROR_CODES in error.js). Message: "ns not found". Note: dropIndexes() on an existing but empty collection (no non-_id indexes) returns immediately without error.
  Required handlingCaller MUST catch MongoServerError code 26 in migration scripts that may run before collection creation: try { await collection.dropIndexes(); } catch (error) { if (error instanceof MongoServerError && error.code === 26) { // Collection does not exist yet — skip index cleanup console.warn(`Collection ${collection.collectionName} not found — skipping dropIndexes`); } else { throw error; } }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[14][5]
• withSession · withsession-callback-error-propagates

  error
  WhenThe callback passed to withSession() throws or rejects. Unlike withTransaction(), withSession() does NOT catch or retry errors from the callback — any error thrown inside propagates directly to the caller. endSession() is still called (via finally), but the original error propagates up unchanged. This is a critical behavioral difference from withTransaction().
  ThrowsAny error thrown by the callback propagates unchanged. If the callback performs MongoDB operations without try-catch, typical errors include: MongoNetworkError, MongoServerError, MongoServerSelectionError, or MongoError. The session is always closed via finally, so SESSION_CLOSED or resource leak is NOT the risk here — the callback error is the risk.
  Required handlingCaller MUST wrap withSession() in try-catch OR handle errors inside the callback. This is different from withTransaction() where errors in the callback are retried. A common mistake is using withSession() when withTransaction() was intended: // CORRECT: catch at the withSession call site try { await client.withSession(async (session) => { const docs = await collection.find({}, { session }).toArray(); await otherCollection.insertMany(docs, { session }); }); } catch (error) { console.error('Session operation failed:', error.message); throw error; } Note: endSession() errors are swallowed (squashError) — they do not mask the original callback error. Confirmed from mongo_client.js source.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13][22]
• withSession · withsession-operations-missing-session

  warning
  WhenMongoDB operations inside the withSession callback do NOT pass the session object. Operations run without the session are not part of the session's causal consistency chain and will use separate connections from the pool, bypassing the session's read concern and read preference settings.
  ThrowsDoes not throw — silent behavioral error (operations run outside session context)
  Required handlingCRITICAL: Every MongoDB operation inside withSession MUST pass { session }: // WRONG — operations bypass session await client.withSession(async (session) => { const result = await collection.findOne({ _id: id }); // ❌ Missing session return result; }); // CORRECT await client.withSession(async (session) => { const result = await collection.findOne({ _id: id }, { session }); // ✅ return result; }); This is the same session-passing requirement as withTransaction(), but withSession() is used more often for simple operations where the mistake is easier to make.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[22][13]
• rename · rename-target-exists

  error
  WhenThe target collection name already exists in the database and dropTarget option is not set to true. By default, rename() refuses to overwrite an existing collection. Common in blue-green migrations where the production collection exists and a new version was loaded into a temp collection.
  ThrowsMongoServerError with message containing "target namespace exists" or similar, from the MongoDB server's renameCollection command. The exact codeName varies by server version. dropTarget: true option allows overwriting.
  Required handlingCaller MUST either set dropTarget: true (destructive) or drop the target first: // Option 1: atomic rename-with-drop (atomic on single-node, not on sharded) await collection.rename('users_new', { dropTarget: true }); // Option 2: drop then rename (two-step, brief downtime window) try { await db.dropCollection('users_backup'); } catch (e) { /* ignore not-found */ } await collection.rename('users_backup'); CRITICAL: dropTarget: true is NOT atomic on sharded clusters — there is a brief window where neither old nor new collection is accessible.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23][24]
• rename · rename-no-try-catch

  error
  Whenrename() is called without try-catch. Network errors during the rename admin command (which runs against the admin database) cause the Promise to reject. The rename is atomic on standalone and replica sets but not on sharded clusters.
  ThrowsMongoNetworkError (connection failure during rename command), MongoServerError (insufficient permissions — rename requires admin privileges, or source collection does not exist — NamespaceNotFound code 26).
  Required handlingCaller MUST wrap rename() in try-catch. Source collection not existing is a MongoServerError with NamespaceNotFound (code 26): try { const newCollection = await collection.rename('users_v2'); return newCollection; } catch (error) { if (error instanceof MongoServerError && error.code === 26) { throw new Error(`Source collection does not exist`); } throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23][24]
• bulkWrite · clientbulkwrite-execution-error

  error
  WhenMongoClient.bulkWrite() is called against a MongoDB server version older than 8.0, OR the bulkWrite admin command is unavailable for the connection's wire version, OR autoEncryption is configured on the MongoClient (FLE/CSFLE+MongoClient.bulkWrite is explicitly unsupported in 7.x — `throw new MongoInvalidArgumentError('MongoClient bulkWrite does not currently support automatic encryption.')` is unconditional when autoEncrypter is present), OR an empty models array is passed (`throw new MongoClientBulkWriteExecutionError('No client bulk write models were provided.')`), OR an unacknowledged write concern (w:0) is combined with `verboseResults: true` or `ordered: true` (both raise MongoInvalidArgumentError synchronously).
  ThrowsMongoClientBulkWriteExecutionError (extends MongoRuntimeError) — pre-flight argument / configuration failure before any server round trip. MongoInvalidArgumentError — autoEncryption-unsupported or unacknowledged-but-verbose configuration. These rejections happen synchronously in the async function body so callers without try-catch hit an unhandled rejection.
  Required handlingCaller MUST wrap MongoClient.bulkWrite in try-catch. The most common production failure mode for this API in 2026 is calling it against a MongoDB Atlas cluster still on the 7.0 LTS line — the call rejects with a server-side "Unknown command: 'bulkWrite'" error, not the Collection.bulkWrite fallback developers may expect. Detect this case and either downgrade to per-collection Collection.bulkWrite loops or surface a deployment-level error: do not retry blindly. Pattern: try { const result = await client.bulkWrite([ { namespace: 'app.orders', name: 'insertOne', document: order }, { namespace: 'app.outbox', name: 'insertOne', document: event } ]); } catch (error) { if (error instanceof MongoClientBulkWriteExecutionError) { // empty models / autoEncryption / w:0 misconfiguration — caller bug throw error; } if (error instanceof MongoServerError && /Unknown command/.test(error.message)) { // Server < 8.0 — fall back to per-collection bulkWrite return await fallbackPerCollection(...); } throw error; }
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[25][13][26]
• bulkWrite · clientbulkwrite-partial-failure-not-inspected

  error
  WhenMongoClient.bulkWrite() throws MongoClientBulkWriteError mid-batch. Unlike a straightforward rejection, this error carries three structured fields with partial-success data: writeConcernErrors (Document[]), writeErrors (Map<number, ClientBulkWriteError>), and partialResult?: ClientBulkWriteResult. The driver will have already split the user's models list into multiple admin/$cmd round trips when the payload exceeds maxMessageSizeBytes — partial failures across batches are the norm at scale, not the exception.
  ThrowsMongoClientBulkWriteError (extends MongoServerError) with writeErrors map keyed by the user's models[] index and a partialResult holding the successful writes. Confirmed from error.ts class definition + executor.ts results_merger.
  Required handlingCaller MUST destructure partialResult and writeErrors when catching MongoClientBulkWriteError. A naive `catch (error) { logger.error(error.message); throw error; }` discards the partial-success information — the application then either double-applies the successful writes on retry (causing duplicate-key collisions on insertOne models) or silently drops them entirely. The fix is to treat the success indices in partialResult as committed and retry only the writeErrors-indexed entries with idempotency keys: try { await client.bulkWrite(models); } catch (error) { if (error instanceof MongoClientBulkWriteError) { const succeeded = error.partialResult; // may be undefined if zero ops landed for (const [index, writeError] of error.writeErrors) { console.error('Op failed:', models[index], writeError); } // Retry only error.writeErrors entries, not the full models array throw new PartialBulkWriteError(error.partialResult, error.writeErrors); } throw error; }
  costcriticalin prodsilent failureusers seelost datavisibilitysilent
  Sources[25][5]
• bulkWrite · clientbulkwrite-cursor-exhaustion-error

  error
  WhenThe MongoClient.bulkWrite executor opens a ClientBulkWriteCursor per command batch and exhausts it to merge results. If cursor exhaustion fails (network drop between first batch and getMore, server-side cursor timeout, connection pool exhaustion), MongoClientBulkWriteCursorError is thrown. The cursor framework partially commits early batches before the failure — the server-side state is "some writes applied, some unknown".
  ThrowsMongoClientBulkWriteCursorError (extends MongoRuntimeError). Confirmed from error.ts class definition. The error message names the underlying cursor failure but does NOT carry a partialResult — unlike MongoClientBulkWriteError, the cursor variant indicates the bulk write reached an indeterminate state mid-stream.
  Required handlingCaller MUST distinguish MongoClientBulkWriteCursorError from MongoClientBulkWriteError. The cursor variant means "we got some confirmations and then lost the stream" — do NOT retry the entire models[] array as if the operation never started. Idempotency keys on insertOne models become mandatory; for update/replace models, write a reconciliation pass that checks the target documents' state before retrying. In high-throughput pipelines, prefer ordered:false to localize the damage to specific indices when the cursor disconnects: try { await client.bulkWrite(models, { ordered: false }); } catch (error) { if (error instanceof MongoClientBulkWriteCursorError) { // Indeterminate state — reconcile target documents instead of replaying await reconcileFromTargetDocs(models); throw error; } if (error instanceof MongoClientBulkWriteError) { // Determinate partial-success — use partialResult + writeErrors throw new PartialBulkWriteError(error.partialResult, error.writeErrors); } throw error; }
  costcriticalin proddelayed failureusers seelost datavisibilitysilent
  Sources[5][26]
• GridFSBucket.delete · gridfs-delete-file-not-found

  error
  WhenThe provided ObjectId does not match any document in the bucket's files collection. GridFSBucket.delete() considers a missing file an error, NOT an idempotent no-op: after deleting orphaned chunks the implementation throws MongoRuntimeError with message `File not found for id <id>`. This catches developers by surprise because comparable APIs (Collection.deleteOne, dropIfExists) treat absence as success.
  ThrowsMongoRuntimeError with message containing `File not found for id`. Confirmed from gridfs/index.ts: `throw new MongoRuntimeError(File not found for id ${id})` after chunks cleanup. Driver TODO(NODE-3483) tracks renaming this to a more specific MongoGridFSFileNotFoundError — until then, message-matching is the only way to distinguish file-not-found from a real I/O failure.
  Required handlingCaller MUST catch MongoRuntimeError and decide whether to treat file-not-found as a success (idempotent delete) or a failure (audit-required state). In file-lifecycle workflows where the delete is the result of a user action (e.g. "delete attachment"), missing-file usually IS the desired final state and the throw should be swallowed. In garbage-collection or migration code, missing-file may indicate a previous incomplete run and must be logged: try { await bucket.delete(fileId); } catch (error) { if (error instanceof MongoRuntimeError && /File not found/.test(error.message)) { // Idempotent path: file already gone — fine for user-initiated delete return; } throw error; } Do NOT use a bare `try {} catch {}` to silently swallow all errors here — chunks collection deletion failures (network, write concern) also surface as thrown errors and must propagate.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[27][28]
• GridFSBucket.delete · gridfs-delete-orphaned-chunks-on-files-failure

  error
  WhenImplementation order: GridFSBucket.delete() first calls _filesCollection.deleteOne then _chunksCollection.deleteMany. If the files-collection delete succeeds but the chunks-collection delete fails (write concern not met on replica set, network drop mid-call, write conflict), the file metadata is gone but the storage chunks remain orphaned in the chunks collection. The Promise rejects with the underlying MongoServerError/MongoNetworkError from deleteMany, but the partial deletion is NOT rolled back — there is no transaction.
  ThrowsMongoServerError or MongoNetworkError from the chunks collection deleteMany call, or MongoOperationTimeoutError if timeoutMS elapses between the two collection operations. Confirmed from gridfs/index.ts source — the chunks deletion is unconditional after the files deletion and any error from it propagates unchanged.
  Required handlingCaller MUST wrap GridFSBucket.delete in try-catch AND have an orphan-chunks reconciliation strategy. When the files-collection delete succeeded but chunks delete failed, the bucket is in an inconsistent state: a periodic GC job must scan the chunks collection for files_id values with no matching files document and clean them up. Pattern: try { await bucket.delete(fileId); } catch (error) { // We do not know whether files-side succeeded — re-checking files-collection // tells us which half of the operation completed const stillExists = await bucket.find({ _id: fileId }).hasNext(); if (!stillExists) { // files-side succeeded, chunks-side failed — enqueue orphan cleanup await orphanChunkQueue.enqueue(fileId); } throw error; } For high-volume buckets, run a daily orphan-chunks sweep regardless of error handling at call sites — single-app catches will inevitably be missed.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[27][28]
• GridFSBucket.rename · gridfs-rename-file-not-found

  error
  WhenThe provided ObjectId does not match any document in the bucket's files collection. GridFSBucket.rename() throws MongoRuntimeError when matchedCount === 0 from the underlying updateOne. Common in workflows where a file is renamed shortly after a concurrent delete, or where the caller assumes the file exists from a stale cache.
  ThrowsMongoRuntimeError with message containing `File with id <id> not found`. Confirmed from gridfs/index.ts: `throw new MongoRuntimeError(File with id ${id} not found)` after the updateOne returns matchedCount === 0. Like GridFSBucket.delete, this is NOT a specific MongoGridFSFileNotFoundError yet — message-matching is required.
  Required handlingCaller MUST catch MongoRuntimeError. Unlike delete(), missing-file on rename almost never represents the desired end state — surface it as an explicit error to the caller rather than swallowing: try { await bucket.rename(fileId, newFilename); } catch (error) { if (error instanceof MongoRuntimeError && /File with id .* not found/.test(error.message)) { throw new ApplicationError('FILE_GONE', `Cannot rename: file ${fileId} no longer exists`); } throw error; } Network errors from updateOne (MongoNetworkError, MongoServerSelectionError) and server errors (write concern, validation) propagate unchanged — they are retryable in a way that file-not-found is not.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[27][28]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

MongoError (base class)
├── MongoDriverError (client-side errors, string error codes)
├── MongoServerError (server-side errors, numeric error codes)
│   ├── MongoWriteConcernError
│   └── MongoBulkWriteError
├── MongoNetworkError
│   ├── MongoNetworkTimeoutError
│   ├── MongoServerSelectionError
│   └── MongoWaitQueueTimeoutError
├── MongoParseError
└── MongoError (generic fallback)