Provided by: libmongoc-doc_1.16.1-1build2_all 
NAME
mongoc_errors - Error Reporting « index
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.
See also: Handling Errors in libbson.
┌────────────────────────────────────┬──────────────────────────────────────────────┬──────────────────────────────────────────┐
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_CLIENT │ MONGOC_ERROR_CLIENT_TOO_BIG │ You tried to send a │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_AUTHENTICATE │ Wrong credentials, or │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER │ You tried an SSL │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_IN_EXHAUST │ You began iterating an │
│ │ │ mongoc_client_t. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_SESSION_FAILURE │ Failure related to │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_ARG │ Failure related to │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_STATE │ Failure related to │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_STREAM │ MONGOC_ERROR_STREAM_NAME_RESOLUTION │ DNS failure. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_STREAM_SOCKET │ Timeout communicating │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_STREAM_CONNECT │ Failed to connect to │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_PROTOCOL │ MONGOC_ERROR_PROTOCOL_INVALID_REPLY │ Corrupt response from │
└────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────┘
│ │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION │ The server version is │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_CURSOR │ MONGOC_ERROR_CURSOR_INVALID_CURSOR │ You passed bad arguments │
│ │ │ mongoc_collection_find_with_opts, │
│ │ │ mongoc_cursor_next on a │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN │ A resume token was not returned │
│ │ │ mongoc_change_stream_next │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_QUERY │ MONGOC_ERROR_QUERY_FAILURE │ Error API Version 1: Server error │
│ │ │ error message is in message. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SERVER │ MONGOC_ERROR_QUERY_FAILURE │ Error API Version 2: Server error │
│ │ │ error message is in message. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SASL │ A SASL error code. │ man sasl_errors for a list of │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_BSON │ MONGOC_ERROR_BSON_INVALID │ You passed an invalid or │
│ │ │ 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 │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION │ You tried to use a command option │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_DUPLICATE_KEY │ An insert or update failed │
│ │ │ _id or other unique-index │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_MAX_TIME_MS_EXPIRED │ The operation failed because │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ MONGOC_ERROR_SERVER_SELECTION_INVALID_ID │ The serverId option for an │
│ │ │ (denoted by the sessionId │
└────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────┘
│MONGOC_ERROR_COMMAND │ Error code from server. │ Error API Version 1: Server error │
│ │ │ message is in message. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SERVER │ Error code from server. │ Error API Version 2: 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 │ Error code from server. │ Error API Version 1: 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 │ Error code from server. │ Error API Version 2: 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 │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ 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 collection. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│ │ 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 authentication. │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SERVER_SELECTION │ MONGOC_ERROR_SERVER_SELECTION_FAILURE │ No replica set member or mongos is │
│ │ │ mongoc_read_prefs_t. │
└────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────┘
│MONGOC_ERROR_WRITE_CONCERN │ Error code from server. │ There was a write concern error or │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_TRANSACTION │ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start a transaction │
├────────────────────────────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_CLIENT_SIDE_ENCRYPTION │ Error code produced by libmongocrypt. │ An error occurred in the library │
└────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────┘
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.
SEE ALSO
MongoDB Server Error Codes
AUTHOR
MongoDB, Inc
COPYRIGHT
2017-present, MongoDB, Inc