Install Now
Many C Driver functions report errors by returning false or -1 and filling out a bson_error_t structure
Contents
Copyright
2009-present, MongoDB, Inc.
1.30.4 Jun 08, 2025 MONGOC_ERRORS(3)
Description
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.
SEEALSO:HandlingErrorsinlibbson.
┌─────────────────────────────────────┬──────────────────────────────────────────────┬────────────────────────────────────────────┐
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_CLIENT │ MONGOC_ERROR_CLIENT_TOO_BIG │ You tried to send a message │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_AUTHENTICATE │ Wrong credentials, or │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER │ You tried an TLS connection │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_IN_EXHAUST │ You began iterating an │
│ │ │ mongoc_client_t. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_SESSION_FAILURE │ Failure related to creating │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_ARG │ Failure related to arguments │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_STATE │ Failure related to In-Use │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_INVALID_LOAD_BALANCER │ You attempted to connect to │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_STREAM │ MONGOC_ERROR_STREAM_NAME_RESOLUTION │ DNS failure. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_STREAM_SOCKET │ Timeout communicating with │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_STREAM_CONNECT │ Failed to connect to server. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_PROTOCOL │ MONGOC_ERROR_PROTOCOL_INVALID_REPLY │ Corrupt response from │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION │ The server version is too │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_CURSOR │ MONGOC_ERROR_CURSOR_INVALID_CURSOR │ You passed bad arguments to │
│ │ │ mongoc_collection_find_with_opts(), │
│ │ │ mongoc_cursor_next() on a │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN │ A resume token was not returned in │
│ │ │ mongoc_change_stream_next() │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_QUERY │ MONGOC_ERROR_QUERY_FAILURE │ ErrorAPIVersion1: Server error │
│ │ │ error message is in message. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_SERVER │ MONGOC_ERROR_QUERY_FAILURE │ ErrorAPIVersion2: Server error │
│ │ │ error message is in message. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_SASL │ A SASL error code. │ mansasl_errors for a list of │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_BSON │ MONGOC_ERROR_BSON_INVALID │ You passed an invalid or oversized │
│ │ │ mongoc_collection_create_index() │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_NAMESPACE │ MONGOC_ERROR_NAMESPACE_INVALID │ You tried to create a collection │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_COMMAND │ MONGOC_ERROR_COMMAND_INVALID_ARG │ Many functions set this error code │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION │ You tried to use a command option │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_DUPLICATE_KEY │ An insert or update failed because │
│ │ │ because of a duplicate _id or other │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_MAX_TIME_MS_EXPIRED │ The operation failed because │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_SERVER_SELECTION_INVALID_ID │ The serverId option for an │
│ │ │ session (denoted by the sessionId │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_COMMAND │ Errorcodefromserver. │ ErrorAPIVersion1: Server error │
│ │ │ message is in message. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_SERVER │ Errorcodefromserver. │ ErrorAPIVersion2: Server error │
│ │ │ message is in message. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_COLLECTION │ MONGOC_ERROR_COLLECTION_INSERT_FAILED, │ Invalid or empty input to │
│ │ MONGOC_ERROR_COLLECTION_UPDATE_FAILED, │ mongoc_collection_insert_one(), │
│ │ MONGOC_ERROR_COLLECTION_DELETE_FAILED. │ 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_COLLECTION │ Errorcodefromserver. │ ErrorAPIVersion1: Server error │
│ │ │ mongoc_collection_insert_one(), │
│ │ │ mongoc_collection_insert_bulk(), │
│ │ │ mongoc_collection_update_one(), │
│ │ │ mongoc_collection_update_many(), │
│ │ │ mongoc_collection_replace_one(), │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_SERVER │ Errorcodefromserver. │ ErrorAPIVersion2: Server error │
│ │ │ mongoc_collection_insert_one(), │
│ │ │ mongoc_collection_insert_bulk(), │
│ │ │ mongoc_collection_update_one(), │
│ │ │ mongoc_collection_update_many(), │
│ │ │ mongoc_collection_replace_one(), │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_GRIDFS │ MONGOC_ERROR_GRIDFS_CHUNK_MISSING │ The GridFS file is missing a │
│ │ │ document in its chunks collection. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_GRIDFS_CORRUPT │ A data inconsistency was detected │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_GRIDFS_INVALID_FILENAME │ You passed a NULL filename to │
│ │ │ mongoc_gridfs_remove_by_filename(). │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_GRIDFS_PROTOCOL_ERROR │ You called │
│ │ │ mongoc_gridfs_file_set_id() after │
│ │ │ mongoc_gridfs_file_save(), or tried │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_GRIDFS_BUCKET_FILE_NOT_FOUND │ A GridFS file is missing from files │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_GRIDFS_BUCKET_STREAM │ An error occurred on a stream │
│ │ │ mongoc_gridfs_bucket_upload_from_stream(). │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_SCRAM │ MONGOC_ERROR_SCRAM_PROTOCOL_ERROR │ Failure in SCRAM-SHA-1 or SCRAM-SHA-256 │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ 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. │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_WRITE_CONCERN │ Errorcodefromserver. │ There was a writeconcern error or timeout │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_TRANSACTION │ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start a transaction when │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_CLIENT_SIDE_ENCRYPTION │ Error code produced by libmongocrypt. │ An error occurred in the library │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_AZURE │ MONGOC_ERROR_KMS_SERVER_HTTP │ An Azure HTTP service responded with an │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_KMS_SERVER_BAD_JSON │ An Azure service responded with invalid │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ MONGOC_ERROR_GCP │ MONGOC_ERROR_KMS_SERVER_HTTP │ A GCP HTTP service responded with an error │
├─────────────────────────────────────┼──────────────────────────────────────────────┼────────────────────────────────────────────┤
│ │ MONGOC_ERROR_KMS_SERVER_BAD_JSON │ A GCP service responded with invalid JSON │
└─────────────────────────────────────┴──────────────────────────────────────────────┴────────────────────────────────────────────┘
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.
TransientTransactionError
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.
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.
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 Source │ API Version 1 │ API Version 2 │
├───────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
│ mongoc_cursor_error() │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
├───────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
│ mongoc_client_command_with_opts(), │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
│ mongoc_database_command_with_opts(), │ │ │
│ and other command functions │ │ │
├───────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
│ mongoc_collection_count_with_opts() │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
│ mongoc_client_get_database_names_with_opts(), │ │ │
│ and other command helper functions │ │ │
├───────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
│ mongoc_collection_insert_one() │ MONGOC_ERROR_COMMAND │ MONGOC_ERROR_SERVER │
│ 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_bulk_operation_execute() │ MONGOC_ERROR_COMMAND │ MONGOC_ERROR_SERVER │
├───────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
│ Write-concern timeout │ MONGOC_ERROR_WRITE_CONCERN │ 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().
SEEALSO:MongoDBServerErrorCodes
PNG Icons
