.\" Man page generated from reStructuredText.
.
.TH "MONGOC_ERRORS" "3" "Jun 04, 2021" "1.17.6" "libmongoc"
.SH NAME
mongoc_errors \- Error Reporting
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
« index
.SH DESCRIPTION
.sp
Many C Driver functions report errors by returning \fBfalse\fP or \-1 and filling out a \fI\%bson_error_t\fP structure with an error domain, error code, and message. Use \fBdomain\fP to determine which subsystem generated the error, and \fBcode\fP for the specific error. \fBmessage\fP is a human\-readable error description.
.sp
See also: \fI\%Handling Errors in libbson\fP\&.
.TS
center;
|l|l|l|.
_
T{
Domain
T}	T{
Code
T}	T{
Description
T}
_
T{
\fBMONGOC_ERROR_CLIENT\fP
T}	T{
\fBMONGOC_ERROR_CLIENT_TOO_BIG\fP
T}	T{
You tried to send a message larger than the server\(aqs max message size.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CLIENT_AUTHENTICATE\fP
T}	T{
Wrong credentials, or failure sending or receiving authentication messages.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER\fP
T}	T{
You tried an TLS connection but the driver was not built with TLS.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CLIENT_IN_EXHAUST\fP
T}	T{
You began iterating an exhaust cursor, then tried to begin another operation with the same \fBmongoc_client_t\fP\&.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CLIENT_SESSION_FAILURE\fP
T}	T{
Failure related to creating or using a logical session.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_ARG\fP
T}	T{
Failure related to arguments passed when initializing Client\-Side Field Level Encryption.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_STATE\fP
T}	T{
Failure related to Client\-Side Field Level Encryption.
T}
_
T{
\fBMONGOC_ERROR_STREAM\fP
T}	T{
\fBMONGOC_ERROR_STREAM_NAME_RESOLUTION\fP
T}	T{
DNS failure.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_STREAM_SOCKET\fP
T}	T{
Timeout communicating with server, or connection closed.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_STREAM_CONNECT\fP
T}	T{
Failed to connect to server.
T}
_
T{
\fBMONGOC_ERROR_PROTOCOL\fP
T}	T{
\fBMONGOC_ERROR_PROTOCOL_INVALID_REPLY\fP
T}	T{
Corrupt response from server.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION\fP
T}	T{
The server version is too old or too new to communicate with the driver.
T}
_
T{
\fBMONGOC_ERROR_CURSOR\fP
T}	T{
\fBMONGOC_ERROR_CURSOR_INVALID_CURSOR\fP
T}	T{
You passed bad arguments to \fBmongoc_collection_find_with_opts\fP, or you called \fBmongoc_cursor_next\fP on a completed or failed cursor, or the cursor timed out on the server.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN\fP
T}	T{
A resume token was not returned in a document found with \fBmongoc_change_stream_next\fP
T}
_
T{
\fBMONGOC_ERROR_QUERY\fP
T}	T{
\fBMONGOC_ERROR_QUERY_FAILURE\fP
T}	T{
\fI\%Error API Version 1\fP: Server error from command or query. The server error message is in \fBmessage\fP\&.
T}
_
T{
\fBMONGOC_ERROR_SERVER\fP
T}	T{
\fBMONGOC_ERROR_QUERY_FAILURE\fP
T}	T{
\fI\%Error API Version 2\fP: Server error from command or query. The server error message is in \fBmessage\fP\&.
T}
_
T{
\fBMONGOC_ERROR_SASL\fP
T}	T{
A SASL error code.
T}	T{
\fBman sasl_errors\fP for a list of codes.
T}
_
T{
\fBMONGOC_ERROR_BSON\fP
T}	T{
\fBMONGOC_ERROR_BSON_INVALID\fP
T}	T{
You passed an invalid or oversized BSON document as a parameter, or called \fBmongoc_collection_create_index\fP with invalid keys, or the server reply was corrupt.
T}
_
T{
\fBMONGOC_ERROR_NAMESPACE\fP
T}	T{
\fBMONGOC_ERROR_NAMESPACE_INVALID\fP
T}	T{
You tried to create a collection with an invalid name.
T}
_
T{
\fBMONGOC_ERROR_COMMAND\fP
T}	T{
\fBMONGOC_ERROR_COMMAND_INVALID_ARG\fP
T}	T{
Many functions set this error code when passed bad parameters. Print the error message for details.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION\fP
T}	T{
You tried to use a command option the server does not support.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_DUPLICATE_KEY\fP
T}	T{
An insert or update failed because because of a duplicate \fB_id\fP or other unique\-index violation.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_MAX_TIME_MS_EXPIRED\fP
T}	T{
The operation failed because maxTimeMS expired.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_SERVER_SELECTION_INVALID_ID\fP
T}	T{
The \fBserverId\fP option for an operation conflicts with the pinned server for that operation\(aqs client session (denoted by the \fBsessionId\fP option).
T}
_
T{
\fBMONGOC_ERROR_COMMAND\fP
T}	T{
\fI\%Error code from server\fP\&.
T}	T{
\fI\%Error API Version 1\fP: Server error from a command. The server error message is in \fBmessage\fP\&.
T}
_
T{
\fBMONGOC_ERROR_SERVER\fP
T}	T{
\fI\%Error code from server\fP\&.
T}	T{
\fI\%Error API Version 2\fP: Server error from a command. The server error message is in \fBmessage\fP\&.
T}
_
T{
\fBMONGOC_ERROR_COLLECTION\fP
T}	T{
\fBMONGOC_ERROR_COLLECTION_INSERT_FAILED\fP, \fBMONGOC_ERROR_COLLECTION_UPDATE_FAILED\fP, \fBMONGOC_ERROR_COLLECTION_DELETE_FAILED\fP\&.
T}	T{
Invalid or empty input to \fBmongoc_collection_insert_one\fP, \fBmongoc_collection_insert_bulk\fP, \fBmongoc_collection_update_one\fP, \fBmongoc_collection_update_many\fP, \fBmongoc_collection_replace_one\fP, \fBmongoc_collection_delete_one\fP, or \fBmongoc_collection_delete_many\fP\&.
T}
_
T{
\fBMONGOC_ERROR_COLLECTION\fP
T}	T{
\fI\%Error code from server\fP\&.
T}	T{
\fI\%Error API Version 1\fP: Server error from \fBmongoc_collection_insert_one\fP, \fBmongoc_collection_insert_bulk\fP, \fBmongoc_collection_update_one\fP, \fBmongoc_collection_update_many\fP, \fBmongoc_collection_replace_one\fP,
T}
_
T{
\fBMONGOC_ERROR_SERVER\fP
T}	T{
\fI\%Error code from server\fP\&.
T}	T{
\fI\%Error API Version 2\fP: Server error from \fBmongoc_collection_insert_one\fP, \fBmongoc_collection_insert_bulk\fP, \fBmongoc_collection_update_one\fP, \fBmongoc_collection_update_many\fP, \fBmongoc_collection_replace_one\fP,
T}
_
T{
\fBMONGOC_ERROR_GRIDFS\fP
T}	T{
\fBMONGOC_ERROR_GRIDFS_CHUNK_MISSING\fP
T}	T{
The GridFS file is missing a document in its \fBchunks\fP collection.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_GRIDFS_CORRUPT\fP
T}	T{
A data inconsistency was detected in GridFS.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_GRIDFS_INVALID_FILENAME\fP
T}	T{
You passed a NULL filename to \fBmongoc_gridfs_remove_by_filename\fP\&.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_GRIDFS_PROTOCOL_ERROR\fP
T}	T{
You called \fBmongoc_gridfs_file_set_id\fP after \fBmongoc_gridfs_file_save\fP, or tried to write on a closed GridFS stream.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_GRIDFS_BUCKET_FILE_NOT_FOUND\fP
T}	T{
A GridFS file is missing from \fBfiles\fP collection.
T}
_
T{
T}	T{
\fBMONGOC_ERROR_GRIDFS_BUCKET_STREAM\fP
T}	T{
An error occurred on a stream created from a GridFS operation like \fBmongoc_gridfs_bucket_upload_from_stream\fP\&.
T}
_
T{
\fBMONGOC_ERROR_SCRAM\fP
T}	T{
\fBMONGOC_ERROR_SCRAM_PROTOCOL_ERROR\fP
T}	T{
Failure in SCRAM\-SHA\-1 authentication.
T}
_
T{
\fBMONGOC_ERROR_SERVER_SELECTION\fP
T}	T{
\fBMONGOC_ERROR_SERVER_SELECTION_FAILURE\fP
T}	T{
No replica set member or mongos is available, or none matches your read preference, or you supplied an invalid \fBmongoc_read_prefs_t\fP\&.
T}
_
T{
\fBMONGOC_ERROR_WRITE_CONCERN\fP
T}	T{
\fI\%Error code from server\fP\&.
T}	T{
There was a write concern error or timeout from the server.
T}
_
T{
\fBMONGOC_ERROR_TRANSACTION\fP
T}	T{
\fBMONGOC_ERROR_TRANSACTION_INVALID\fP
T}	T{
You attempted to start a transaction when one is already in progress, or commit or abort when there is no transaction.
T}
_
T{
\fBMONGOC_ERROR_CLIENT_SIDE_ENCRYPTION\fP
T}	T{
Error code produced by libmongocrypt.
T}	T{
An error occurred in the library responsible for Client Side Encryption
T}
_
.TE
.SH ERROR LABELS
.sp
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 \fIlabels\fP provide a reliable way to determine how your application should respond to an error.
.sp
Any C Driver function that has a \fI\%bson_t\fP out\-parameter named \fBreply\fP may include error labels to the reply, in the form of a BSON field named "errorLabels" containing an array of strings:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{ "errorLabels": [ "TransientTransactionError" ] }
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use \fBmongoc_error_has_label\fP to test if a reply contains a specific label. See \fBmongoc_client_session_start_transaction\fP for example code that demonstrates the use of error labels in application logic.
.sp
The following error labels are currently defined. Future versions of MongoDB may introduce new labels.
.SS TransientTransactionError
.sp
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.
.SS UnknownTransactionCommitResult
.sp
When \fBmongoc_client_session_commit_transaction\fP 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 \fInot\fP labeled "UnknownTransactionCommitResult", or the application chooses to give up.
.SH SETTING THE ERROR API VERSION
.sp
The driver\(aqs error reporting began with a design flaw: when the error \fIdomain\fP is \fBMONGOC_ERROR_COLLECTION\fP, \fBMONGOC_ERROR_QUERY\fP, or \fBMONGOC_ERROR_COMMAND\fP, the error \fIcode\fP 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.
.sp
For example, if \fBmongoc_collection_update_one\fP sets the error\(aqs domain to \fBMONGOC_ERROR_COLLECTION\fP and its code to 24, the application cannot know whether 24 is the generic driver error code \fBMONGOC_ERROR_COLLECTION_UPDATE_FAILED\fP or the specific server error code "LockTimeout".
.sp
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, \fBMONGOC_ERROR_SERVER\fP\&. In Version 2, error codes originating on the server always have error domain \fBMONGOC_ERROR_SERVER\fP or \fBMONGOC_ERROR_WRITE_CONCERN\fP\&. 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.
.TS
center;
|l|l|l|.
_
T{
Error Source
T}	T{
API Version 1
T}	T{
API Version 2
T}
_
T{
\fBmongoc_cursor_error\fP
T}	T{
\fBMONGOC_ERROR_QUERY\fP
T}	T{
\fBMONGOC_ERROR_SERVER\fP
T}
_
T{
\fBmongoc_client_command_with_opts\fP,
\fBmongoc_database_command_with_opts\fP, and
other command functions
T}	T{
\fBMONGOC_ERROR_QUERY\fP
T}	T{
\fBMONGOC_ERROR_SERVER\fP
T}
_
T{
\fBmongoc_collection_count_with_opts\fP
\fBmongoc_client_get_database_names_with_opts\fP,
and other command helper functions
T}	T{
\fBMONGOC_ERROR_QUERY\fP
T}	T{
\fBMONGOC_ERROR_SERVER\fP
T}
_
T{
\fBmongoc_collection_insert_one\fP
\fBmongoc_collection_insert_bulk\fP
\fBmongoc_collection_update_one\fP
\fBmongoc_collection_update_many\fP
\fBmongoc_collection_replace_one\fP
\fBmongoc_collection_delete_one\fP
\fBmongoc_collection_delete_many\fP
T}	T{
\fBMONGOC_ERROR_COMMAND\fP
T}	T{
\fBMONGOC_ERROR_SERVER\fP
T}
_
T{
\fBmongoc_bulk_operation_execute\fP
T}	T{
\fBMONGOC_ERROR_COMMAND\fP
T}	T{
\fBMONGOC_ERROR_SERVER\fP
T}
_
T{
Write\-concern timeout
T}	T{
\fBMONGOC_ERROR_WRITE_CONCERN\fP
T}	T{
\fBMONGOC_ERROR_WRITE_CONCERN\fP
T}
_
.TE
.sp
The Error API Versions are defined with \fBMONGOC_ERROR_API_VERSION_LEGACY\fP and \fBMONGOC_ERROR_API_VERSION_2\fP\&. Set the version with \fBmongoc_client_set_error_api\fP or \fBmongoc_client_pool_set_error_api\fP\&.
.SH SEE ALSO
.sp
\fI\%MongoDB Server Error Codes\fP
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.