Provided by: libmongoc-doc_1.21.0-1build1_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.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Domain Code Description
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_CLIENT MONGOC_ERROR_CLIENT_TOO_BIG You tried to send a message
larger than the server's max
message size.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_CLIENT_AUTHENTICATE Wrong credentials, or
failure sending or receiving
authentication messages.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER You tried an 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
Client-Side Field Level
Encryption.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_STATE Failure related to
Client-Side Field Level
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_STREAM 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 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.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_CURSOR MONGOC_ERROR_CURSOR_INVALID_CURSOR You 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_TOKEN A resume token was not returned
in a document found with
mongoc_change_stream_next
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_QUERY MONGOC_ERROR_QUERY_FAILURE Error API Version 1: Server error
from command or query. The server
error message is in message.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_SERVER MONGOC_ERROR_QUERY_FAILURE Error API Version 2: Server error
from command or query. The server
error message is in message.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_SASL A SASL error code. 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 called
mongoc_collection_create_index
with invalid keys, or the server
reply was corrupt.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_NAMESPACE MONGOC_ERROR_NAMESPACE_INVALID You tried to create a collection
with an invalid name.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_COMMAND MONGOC_ERROR_COMMAND_INVALID_ARG Many functions set this error
code when passed bad parameters.
Print the error message for
details.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION You tried to use a command option
the server does not support.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_DUPLICATE_KEY An insert or update failed
because because of a duplicate
_id or other unique-index
violation.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_ERROR_MAX_TIME_MS_EXPIRED The operation failed because
maxTimeMS expired.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
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).
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
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.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
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
from
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
from
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 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
1.21.0 Feb 09, 2022 MONGOC_ERRORS(3)