mongoc_errors - Man Page

« libmongoc


Many C Driver functions report errors by returning false or -1 and filling out a bson_error_t structure with an error domain, error code, and message. Use domain to determine which subsystem generated the error, and code for the specific error. message is a human-readable error description.


Handling Errors in libbson.
MONGOC_ERROR_CLIENTMONGOC_ERROR_CLIENT_TOO_BIGYou tried to send a message larger than the server's max message size.
MONGOC_ERROR_CLIENT_AUTHENTICATEWrong credentials, or failure sending or receiving authentication messages.
MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEERYou tried an TLS connection but the driver was not built with TLS.
MONGOC_ERROR_CLIENT_IN_EXHAUSTYou began iterating an exhaust cursor, then tried to begin another operation with the same mongoc_client_t.
MONGOC_ERROR_CLIENT_SESSION_FAILUREFailure related to creating or using a logical session.
MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_ARGFailure related to arguments passed when initializing In-Use Encryption.
MONGOC_ERROR_CLIENT_INVALID_LOAD_BALANCERYou attempted to connect to a MongoDB server behind a load balancer, but the server does not advertize load balanced support.
MONGOC_ERROR_STREAM_SOCKETTimeout communicating with server, or connection closed.
MONGOC_ERROR_STREAM_CONNECTFailed to connect to server.
MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSIONThe server version is too old or too new to communicate with the driver.
MONGOC_ERROR_CURSORMONGOC_ERROR_CURSOR_INVALID_CURSORYou passed bad arguments to mongoc_collection_find_with_opts(), or you called mongoc_cursor_next() on a completed or failed cursor, or the cursor timed out on the server.
MONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKENA resume token was not returned in a document found with mongoc_change_stream_next()
MONGOC_ERROR_QUERYMONGOC_ERROR_QUERY_FAILUREError API Version 1: Server error from command or query. The server error message is in message.
MONGOC_ERROR_SERVERMONGOC_ERROR_QUERY_FAILUREError API Version 2: Server error from command or query. The server error message is in message.
MONGOC_ERROR_SASLA SASL error sasl_errors for a list of codes.
MONGOC_ERROR_BSONMONGOC_ERROR_BSON_INVALIDYou passed an invalid or oversized BSON document as a parameter, or called mongoc_collection_create_index() with invalid keys, or the server reply was corrupt.
MONGOC_ERROR_NAMESPACEMONGOC_ERROR_NAMESPACE_INVALIDYou tried to create a collection with an invalid name.
MONGOC_ERROR_COMMANDMONGOC_ERROR_COMMAND_INVALID_ARGMany functions set this error code when passed bad parameters. Print the error message for details.
MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSIONYou tried to use a command option the server does not support.
MONGOC_ERROR_DUPLICATE_KEYAn insert or update failed because because of a duplicate _id or other unique-index violation.
MONGOC_ERROR_MAX_TIME_MS_EXPIREDThe operation failed because maxTimeMS expired.
MONGOC_ERROR_SERVER_SELECTION_INVALID_IDThe serverId option for an operation conflicts with the pinned server for that operation's client session (denoted by the sessionId option).
MONGOC_ERROR_COMMANDError code from server.Error API Version 1: Server error from a command. The server error message is in message.
MONGOC_ERROR_SERVERError code from server.Error API Version 2: Server error from a command. The server error message is in message.
MONGOC_ERROR_COLLECTIONMONGOC_ERROR_COLLECTION_INSERT_FAILED, MONGOC_ERROR_COLLECTION_UPDATE_FAILED, MONGOC_ERROR_COLLECTION_DELETE_FAILED.Invalid or empty input to mongoc_collection_insert_one(), mongoc_collection_insert_bulk(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(), mongoc_collection_delete_one(), or mongoc_collection_delete_many().
MONGOC_ERROR_COLLECTIONError code from server.Error API Version 1: Server error from mongoc_collection_insert_one(), mongoc_collection_insert_bulk(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(),
MONGOC_ERROR_SERVERError code from server.Error API Version 2: Server error from mongoc_collection_insert_one(), mongoc_collection_insert_bulk(), mongoc_collection_update_one(), mongoc_collection_update_many(), mongoc_collection_replace_one(),
MONGOC_ERROR_GRIDFSMONGOC_ERROR_GRIDFS_CHUNK_MISSINGThe GridFS file is missing a document in its chunks collection.
MONGOC_ERROR_GRIDFS_CORRUPTA data inconsistency was detected in GridFS.
MONGOC_ERROR_GRIDFS_INVALID_FILENAMEYou passed a NULL filename to mongoc_gridfs_remove_by_filename().
MONGOC_ERROR_GRIDFS_PROTOCOL_ERRORYou called mongoc_gridfs_file_set_id() after mongoc_gridfs_file_save(), or tried to write on a closed GridFS stream.
MONGOC_ERROR_GRIDFS_BUCKET_FILE_NOT_FOUNDA GridFS file is missing from files collection.
MONGOC_ERROR_GRIDFS_BUCKET_STREAMAn error occurred on a stream created from a GridFS operation like mongoc_gridfs_bucket_upload_from_stream().
MONGOC_ERROR_SERVER_SELECTIONMONGOC_ERROR_SERVER_SELECTION_FAILURENo replica set member or mongos is available, or none matches your read preference, or you supplied an invalid mongoc_read_prefs_t.
MONGOC_ERROR_WRITE_CONCERNError code from server.There was a write concern error or timeout from the server.
MONGOC_ERROR_TRANSACTIONMONGOC_ERROR_TRANSACTION_INVALIDYou attempted to start a transaction when one is already in progress, or commit or abort when there is no transaction.
MONGOC_ERROR_CLIENT_SIDE_ENCRYPTIONError code produced by libmongocrypt.An error occurred in the library responsible for In-Use Encryption
MONGOC_ERROR_AZUREMONGOC_ERROR_KMS_SERVER_HTTPAn Azure HTTP service responded with an error status
MONGOC_ERROR_KMS_SERVER_BAD_JSONAn Azure service responded with invalid JSON data
MONGOC_ERROR_GCPMONGOC_ERROR_KMS_SERVER_HTTPA GCP HTTP service responded with an error status
MONGOC_ERROR_KMS_SERVER_BAD_JSONA GCP service responded with invalid JSON data

Error Labels

In some cases your application must make decisions based on what category of error the driver has returned, but these categories do not correspond perfectly to an error domain or code. In such cases, error labels provide a reliable way to determine how your application should respond to an error.

Any C Driver function that has a bson_t out-parameter named reply may include error labels to the reply, in the form of 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.

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


Within 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.


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.

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.

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.

Error SourceAPI Version 1API Version 2
mongoc_client_command_with_opts(), mongoc_database_command_with_opts(), and other command functionsMONGOC_ERROR_QUERYMONGOC_ERROR_SERVER
mongoc_collection_count_with_opts() mongoc_client_get_database_names_with_opts(), and other command helper functionsMONGOC_ERROR_QUERYMONGOC_ERROR_SERVER
mongoc_collection_insert_one() mongoc_collection_insert_bulk() mongoc_collection_update_one() mongoc_collection_update_many() mongoc_collection_replace_one() mongoc_collection_delete_one() mongoc_collection_delete_many()MONGOC_ERROR_COMMANDMONGOC_ERROR_SERVER

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().


MongoDB Server Error Codes


MongoDB, Inc


Feb 16, 2024 1.26.0 libmongoc