MONGOC_ERRORS(3)

📦
version 2.5.6 · 16 versions
, in epel 10

💅 MONGOC_ERRORS(3) 💅

libmongoc manual page, API section — « libmongoc - API. bestie, this is the error-code lore, and it's honestly iconic.

✨ DESCRIPTION ✨

okay so many C Driver functions report errors by returning false or -1 and filling out a bson_error_t structure with an error domain, an error code, and a message. Use domain to figure out which subsystem generated the error, and code for the specific error. message is a human-readable error description. literally that's the whole vibe.

🌸 SEE ALSO 🌸

SEE ALSO: Handling Errors in libbson.

now the big code table, grouped by domain so it's readable — every row is here, no cap:

  • MONGOC_ERROR_CLIENT — the client domain:
    • MONGOC_ERROR_CLIENT_TOO_BIG — you tried to send a message larger than the server's max message size. too big, bestie 😭
    • MONGOC_ERROR_CLIENT_AUTHENTICATE — wrong credentials, or failure sending or receiving authentication messages.
    • MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER — you tried a TLS connection but the driver was not built with TLS.
    • MONGOC_ERROR_CLIENT_IN_EXHAUST — you began iterating an exhaust cursor, then tried to begin another operation with the same mongoc_client_t.
    • MONGOC_ERROR_CLIENT_SESSION_FAILURE — failure related to creating or using a logical session.
    • MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_ARG — failure related to arguments passed when initializing In-Use Encryption.
    • MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_STATE — failure related to In-Use Encryption.
    • MONGOC_ERROR_CLIENT_INVALID_LOAD_BALANCER — you attempted to connect to a MongoDB server behind a load balancer, but the server does not advertize load balanced support.
    • MONGOC_ERROR_CLIENT_NOT_READY — you attempted to create a client but did not previously call mongoc_init().
  • MONGOC_ERROR_STREAM — the stream domain:
    • MONGOC_ERROR_STREAM_NAME_RESOLUTION — DNS failure.
    • MONGOC_ERROR_STREAM_SOCKET — timeout communicating with server, or connection closed.
    • MONGOC_ERROR_STREAM_CONNECT — failed to connect to server.
  • MONGOC_ERROR_PROTOCOL — the protocol domain:
    • MONGOC_ERROR_PROTOCOL_INVALID_REPLY — corrupt response from server. 💀
    • MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION — the server version is too old or too new to communicate with the driver.

okay so the table keeps going, bestie — buckle up, we're still in the error-domain zone 💅

  • MONGOC_ERROR_CURSOR
    • MONGOC_ERROR_CURSOR_INVALID_CURSOR — this one's giving “you did too much” 😭 you passed bad arguments to mongoc_collection_find_with_opts(), or you called mongoc_cursor_next() on a cursor that's already completed or has failed, or the cursor timed out on the server. that's it, that's the whole vibe check fail.
    • MONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN — a resume token was not returned in a document found with mongoc_change_stream_next() 🫶 (the domain cell was blank in the original, so yes, it's nesting under MONGOC_ERROR_CURSOR — iykyk)
  • MONGOC_ERROR_QUERY
    • MONGOC_ERROR_QUERY_FAILURE — Error API Version 1: server error from a command or query 🔥 the server error message is in message.
  • MONGOC_ERROR_SERVER
    • MONGOC_ERROR_QUERY_FAILURE — Error API Version 2: server error from a command or query ✨ the server error message is in message. (yes, same code name, different domain — the API version is literally the whole plot twist 💀)
  • MONGOC_ERROR_SASL
    • A SASL error code. — not me handing you off to another manpage, but fr: man sasl_errors for a list of codes 📖
  • MONGOC_ERROR_BSON
    • MONGOC_ERROR_BSON_INVALID — you passed an invalid or oversized BSON document as a parameter, or the server reply was corrupt 🙈 no cap, check your docs.
  • MONGOC_ERROR_NAMESPACE
    • MONGOC_ERROR_NAMESPACE_INVALID — you tried to create a collection with an invalid name 🎀 she said “pick a better name” and honestly? valid.
  • MONGOC_ERROR_COMMAND
    • MONGOC_ERROR_COMMAND_INVALID_ARG — many functions set this error code when passed bad parameters. print the error message for details 🫶 like, the details are literally right there bestie, read them.
    • MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION — you tried to use a command option the server does not support ⭐ the server said “we don't do that here” and honestly it's not wrong.
    • MONGOC_ERROR_DUPLICATE_KEY — an insert or update failed because of a duplicate _id or other unique-index violation 💀 she's already taken. iconic, but taken.
    • MONGOC_ERROR_MAX_TIME_MS_EXPIRED — the operation failed because maxTimeMS expired ⏰ time said “girl, bye.”
    • MONGOC_ERROR_SERVER_SELECTION_INVALID_ID — the serverId option for an operation conflicts with the pinned server for that operation's client session (denoted by the sessionId option) 🦋 two servers, one session, zero chill.
  • MONGOC_ERROR_COMMAND
    • Error code from server. — Error API Version 1: server error from a command 🔥 the server error message is in message.
  • MONGOC_ERROR_SERVER
    • Error code from server. — Error API Version 2: server error from a command 🔥 the server error message is in message.

and yes, you clocked it — MONGOC_ERROR_QUERY_FAILURE and the MONGOC_ERROR_COMMAND + “Error code from server.” rows show up twice on purpose, once per Error API version 🌈 don't merge them in your head, that's how the docs get messy bestie.

  • MONGOC_ERROR_COLLECTION 🗂️ — bestie this one's got a whole little squad of codes under it:
    • MONGOC_ERROR_COLLECTION_INSERT_FAILED, MONGOC_ERROR_COLLECTION_UPDATE_FAILED, MONGOC_ERROR_COLLECTION_DELETE_FAILED — literally means the input you handed to mongoc_collection_insert_one(), mongoc_collection_insert_many(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(), mongoc_collection_delete_one(), or mongoc_collection_delete_many() was invalid or empty. check ur args, babe 😭
    • Error code from server — Error API Version 1 vibes: a server error that came back from mongoc_collection_insert_one(), mongoc_collection_insert_many(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(),
  • MONGOC_ERROR_SERVER 🖥️ — ok so this one's giving similar energy but different lore:
    • Error code from server — Error API Version 2 flavor: a server error straight from mongoc_collection_insert_one(), mongoc_collection_insert_many(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(),
  • MONGOC_ERROR_GRIDFS 🌊 — the whole GridFS drama collection, lowkey iconic:
    • MONGOC_ERROR_GRIDFS_CHUNK_MISSING — the GridFS file is missing a document in its chunks collection 😭 like it literally lost a piece of itself
    • MONGOC_ERROR_GRIDFS_CORRUPT — a data inconsistency was detected in GridFS. something's not adding up bestie 💀
    • MONGOC_ERROR_GRIDFS_INVALID_FILENAME — you passed a NULL filename to mongoc_gridfs_remove_by_filename(). yeah that'll do it 🙈
    • MONGOC_ERROR_GRIDFS_PROTOCOL_ERROR — you called mongoc_gridfs_file_set_id() after mongoc_gridfs_file_save(), or tried to write on a closed GridFS stream. rude of you honestly
    • MONGOC_ERROR_GRIDFS_BUCKET_FILE_NOT_FOUND — a GridFS file is missing from files collection. gone. vanished. not found bestie 🫥
    • MONGOC_ERROR_GRIDFS_BUCKET_STREAM — an error occurred on a stream created from a GridFS operation like mongoc_gridfs_bucket_upload_from_stream()
  • MONGOC_ERROR_SCRAM 🔐
    • MONGOC_ERROR_SCRAM_PROTOCOL_ERROR — failure in SCRAM-SHA-1 or SCRAM-SHA-256 authentication. auth said nope ✨
  • MONGOC_ERROR_SERVER_SELECTION 🎯
    • MONGOC_ERROR_SERVER_SELECTION_FAILURE — no replica set member or mongos is available, or none matches your read preference, or you supplied an invalid mongoc_read_prefs_t. it's giving "everyone's busy rn" energy tbh
  • MONGOC_ERROR_WRITE_CONCERN ✍️
    • Error code from server — there was a write concern error or timeout from the server. the server said "mmm not right now" 😔
  • MONGOC_ERROR_TRANSACTION 🔄
    • MONGOC_ERROR_TRANSACTION_INVALID — you attempted to start a transaction when one is already in progress, or commit or abort when there is no transaction. pick a lane bestie, you can't do both 😭
  • MONGOC_ERROR_CLIENT_SIDE_ENCRYPTION 🕵️
    • Error code produced by libmongocrypt — an error occurred in the library responsible for In-Use Encryption
  • MONGOC_ERROR_AZURE → MONGOC_ERROR_KMS_SERVER_HTTP — an Azure HTTP service responded with an error status 💀
  • MONGOC_ERROR_AZURE → MONGOC_ERROR_KMS_SERVER_BAD_JSON — an Azure service responded with invalid JSON data 😭
  • MONGOC_ERROR_GCP → MONGOC_ERROR_KMS_SERVER_HTTP — a GCP HTTP service responded with an error status
  • MONGOC_ERROR_GCP → MONGOC_ERROR_KMS_SERVER_BAD_JSON — a GCP service responded with invalid JSON data

🌸 ERROR LABELS 🌸

Okay so sometimes your app has to make decisions based on what category of error the driver handed back, but those categories don't map perfectly onto an error domain or code. That's exactly when error labels come through — they're the reliable way to figure out how your application should respond to an error. Periodt.

Any C Driver function that has a bson_t out-parameter named reply may include error labels in that reply, as a BSON field named "errorLabels" containing an array of strings:

{ "errorLabels": [ "TransientTransactionError" ] }

Use mongoc_error_has_label() to test if a reply contains a specific label. See mongoc_client_session_start_transaction() for example code that demonstrates the use of error labels in application logic. iykyk 💅

The following error labels are currently defined. Future versions of MongoDB may introduce new labels.

💫 TransientTransactionError 💫

Inside a multi-document transaction, certain errors can leave the transaction in an unknown or aborted state. These include write conflicts, primary stepdowns, and network errors. In response, the application should abort the transaction and try the same sequence of operations again in a new transaction. No cap — that's the move. 🫶

🌈 UnknownTransactionCommitResult 🌈

When mongoc_client_session_commit_transaction() encounters a network error or certain server errors, it is not known whether the transaction was committed. Applications should attempt to commit the transaction again until: the commit succeeds, the commit fails with an error not labeled "UnknownTransactionCommitResult", or the application chooses to give up. Lowkey stressful, but that's the rule. 😭

🔥 SETTING THE ERROR API VERSION 🔥

The driver's error reporting began with a design flaw: when the error domain is MONGOC_ERROR_COLLECTION, MONGOC_ERROR_QUERY, or MONGOC_ERROR_COMMAND, the error code might originate from the server or the driver. An application cannot always know where an error originated, and therefore cannot tell what the code means. It's giving mystery box, and not in a fun way. 🙈

For example, if mongoc_collection_update_one() sets the error's domain to MONGOC_ERROR_COLLECTION and its code to 24, the application cannot know whether 24 is the generic driver error code MONGOC_ERROR_COLLECTION_UPDATE_FAILED or the specific server error code "LockTimeout".

To fix this flaw while preserving backward compatibility, the C Driver 1.4 introduces "Error API Versions". Version 1, the default Error API Version, maintains the flawed behavior. Version 2 adds a new error domain, MONGOC_ERROR_SERVER. In Version 2, error codes originating on the server always have error domain MONGOC_ERROR_SERVER or MONGOC_ERROR_WRITE_CONCERN. When the driver uses Version 2 the application can always determine the origin and meaning of error codes. New applications should use Version 2, and existing applications should be updated to use Version 2 as well. Slay. ✨

Vibe check on the whole mapping, bestie — here's every row:

  • mongoc_cursor_error() — API Version 1: MONGOC_ERROR_QUERY; API Version 2: MONGOC_ERROR_SERVER
  • mongoc_client_command_with_opts(), mongoc_database_command_with_opts(), and other command functions — API Version 1: MONGOC_ERROR_QUERY; API Version 2: MONGOC_ERROR_SERVER
  • mongoc_client_get_database_names_with_opts() and other command helper functions — API Version 1: MONGOC_ERROR_QUERY; API Version 2: MONGOC_ERROR_SERVER
  • mongoc_collection_insert_one(), mongoc_collection_insert_many(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(), mongoc_collection_delete_one(), mongoc_collection_delete_many() — API Version 1: MONGOC_ERROR_COMMAND; API Version 2: MONGOC_ERROR_SERVER
  • mongoc_bulk_operation_execute() — API Version 1: MONGOC_ERROR_COMMAND; API Version 2: MONGOC_ERROR_SERVER
  • Write-concern timeout — API Version 1: MONGOC_ERROR_WRITE_CONCERN; API Version 2: MONGOC_ERROR_WRITE_CONCERN

The Error API Versions are defined with MONGOC_ERROR_API_VERSION_LEGACY and MONGOC_ERROR_API_VERSION_2. Set the version with mongoc_client_set_error_api() or mongoc_client_pool_set_error_api().

👀 SEE ALSO 👀

  • MongoDB Server Error Codes

💜 AUTHOR 💜

MongoDB, Inc

2009-present, MongoDB, Inc.

💖 That's a wrap on MONGOC_ERRORS(3), bestie — MongoDB C Driver docs, version 2.5.6, dated Oct 09, 2026. Periodt. 💅✨

📦 where this page comes from