FreeBSD Manual Pages
MONGOC_ERRORS(3) libmongoc MONGOC_ERRORS(3) libmongoc - API 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 er- ror, and code for the specific error. message is a human-readable error description. SEE ALSO: Handling Errors in libbson. +---------------------+----------------------------------+--------------------------------------------+ | Code | Description | | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_CLIENT | MONGOC_ER- | You tried to send a | | | ROR_CLIENT_TOO_BIG | message larger than | | | | the server's max | | | | message size. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | Wrong credentials, | | | ROR_CLIENT_AUTHEN- | or failure sending | | | TICATE | or receiving au- | | | | thentication mes- | | | | sages. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | You tried an TLS | | | ROR_CLIENT_NO_AC- | connection but the | | | CEPTABLE_PEER | driver was not | | | | built with TLS. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | You began iterating | | | ROR_CLIENT_IN_EX- | an exhaust cursor, | | | HAUST | then tried to begin | | | | another operation | | | | with the same | | | | mongoc_client_t. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | Failure related to | | | ROR_CLIENT_SES- | creating or using a | | | SION_FAILURE | logical session. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | Failure related to | | | ROR_CLIENT_IN- | arguments passed | | | VALID_ENCRYP- | when initializing | | | TION_ARG | In-Use Encryption. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | Failure related to | | | ROR_CLIENT_IN- | In-Use Encryption. | | | VALID_ENCRYP- | | | | TION_STATE | | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | You attempted to | | | ROR_CLIENT_IN- | connect to a Mon- | | | VALID_LOAD_BALANCER | goDB server behind | | | | a load balancer, | | | | but the server does | | | | not advertize load | | | | balanced support. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_STREAM | MONGOC_ER- | DNS failure. | | | ROR_STREAM_NAME_RES- | | | | OLUTION | | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | Timeout communicat- | | | ROR_STREAM_SOCKET | ing with server, or | | | | connection closed. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | Failed to connect | | | ROR_STREAM_CONNECT | to server. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_PROTO- | MONGOC_ERROR_PROTO- | Corrupt response | | COL | COL_INVALID_REPLY | from server. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_PROTO- | The server version | | | COL_BAD_WIRE_VERSION | is too old or too | | | | new to communicate | | | | with the driver. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_CURSOR | MONGOC_ERROR_CUR- | You passed bad ar- | | | SOR_INVALID_CURSOR | guments 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_ER- | A resume token was not returned in | | | ROR_CHANGE_STREAM_NO_RE- | a document found with | | | SUME_TOKEN | mongoc_change_stream_next() | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_QUERY | MONGOC_ERROR_QUERY_FAIL- | Error API Version 1: Server error | | | URE | from command or query. The server | | | | error message is in message. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_SERVER | MONGOC_ERROR_QUERY_FAIL- | Error API Version 2: Server error | | | URE | 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_IN- | You passed an invalid or oversized | | | VALID | BSON document as a parameter, or | | | | called | | | | mongoc_collection_create_index() | | | | with invalid keys, or the server | | | | reply was corrupt. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_NAME- | MONGOC_ERROR_NAME- | You tried to create a collection | | SPACE | SPACE_INVALID | with an invalid name. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_COM- | MONGOC_ERROR_COMMAND_IN- | Many functions set this error code | | MAND | VALID_ARG | when passed bad parameters. Print | | | | the error message for details. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_PROTO- | You tried to use a command option | | | COL_BAD_WIRE_VERSION | the server does not support. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_DUPLI- | An insert or update failed because | | | CATE_KEY | because of a duplicate _id or other | | | | unique-index violation. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | The operation failed because max- | | | ROR_MAX_TIME_MS_EXPIRED | TimeMS expired. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_SERVER_SE- | The serverId option for an opera- | | | LECTION_INVALID_ID | tion conflicts with the pinned | | | | server for that operation's client | | | | session (denoted by the sessionId | | | | option). | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_COM- | Error code from server. | Error API Version 1: Server error | | MAND | | 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_COL- | MONGOC_ERROR_COLLEC- | Invalid or empty input to | | LECTION | TION_INSERT_FAILED, MON- | mongoc_collection_insert_one(), | | | GOC_ERROR_COLLECTION_UP- | mongoc_collection_insert_bulk(), | | | DATE_FAILED, MONGOC_ER- | mongoc_collection_update_one(), | | | ROR_COLLEC- | mongoc_collection_update_many(), | | | TION_DELETE_FAILED. | mongoc_collection_replace_one(), | | | | mongoc_collection_delete_one(), or | | | | mongoc_collection_delete_many(). | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_COL- | Error code from server. | Error API Version 1: Server error | | LECTION | | 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_ER- | The GridFS file is missing a docu- | | | ROR_GRIDFS_CHUNK_MISSING | ment in its chunks collection. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_GRIDFS_COR- | A data inconsistency was detected | | | RUPT | in GridFS. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_GRIDFS_IN- | You passed a NULL filename to | | | VALID_FILENAME | mongoc_gridfs_remove_by_filename(). | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_GRIDFS_PRO- | You called | | | TOCOL_ERROR | mongoc_gridfs_file_set_id() after | | | | mongoc_gridfs_file_save(), or tried | | | | to write on a closed GridFS stream. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | A GridFS file is missing from files | | | ROR_GRIDFS_BUCKET_FILE_NOT_FOUND | collection. | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ER- | An error occurred on a stream cre- | | | ROR_GRIDFS_BUCKET_STREAM | ated from a GridFS operation like | | | | mongoc_gridfs_bucket_upload_from_stream(). | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_SCRAM | MONGOC_ERROR_SCRAM_PROTOCOL_ER- | Failure in SCRAM-SHA-1 or SCRAM-SHA-256 | | | ROR | authentication. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ER- | MONGOC_ERROR_SERVER_SELEC- | No replica set member or mongos is avail- | | ROR_SERVER_SELEC- | TION_FAILURE | able, or none matches your read prefer- | | TION | | ence, or you supplied an invalid | | | | mongoc_read_prefs_t. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ER- | Error code from server. | There was a write concern error or timeout | | ROR_WRITE_CONCERN | | from the server. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_TRANS- | MONGOC_ERROR_TRANSACTION_INVALID | You attempted to start a transaction when | | ACTION | | one is already in progress, or commit or | | | | abort when there is no transaction. | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ER- | Error code produced by libmon- | An error occurred in the library responsi- | | ROR_CLIENT_SIDE_EN- | gocrypt. | ble for In-Use Encryption | | CRYPTION | | | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_AZURE | MONGOC_ERROR_KMS_SERVER_HTTP | An Azure HTTP service responded with an | | | | error status | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_KMS_SERVER_BAD_JSON | An Azure service responded with invalid | | | | JSON data | +---------------------+----------------------------------+--------------------------------------------+ | MONGOC_ERROR_GCP | MONGOC_ERROR_KMS_SERVER_HTTP | A GCP HTTP service responded with an error | | | | status | +---------------------+----------------------------------+--------------------------------------------+ | | MONGOC_ERROR_KMS_SERVER_BAD_JSON | A GCP service responded with invalid JSON | | | | data | +---------------------+----------------------------------+--------------------------------------------+ ERROR LABELS In some cases your application must make decisions based on what cate- gory of error the driver has returned, but these categories do not cor- respond perfectly to an error domain or code. In such cases, error la- bels 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 la- bel. 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 con- flicts, primary stepdowns, and network errors. In response, the appli- cation should abort the transaction and try the same sequence of opera- tions 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_ER- ROR_COMMAND, the error code might originate from the server or the dri- ver. 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_COLLEC- TION_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 do- main, MONGOC_ERROR_SERVER. In Version 2, error codes originating on the server always have error domain MONGOC_ERROR_SERVER or MONGOC_ER- ROR_WRITE_CONCERN. When the driver uses Version 2 the application can always determine the origin and meaning of error codes. New applica- tions 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_COM- | MONGOC_ERROR_SERVER | | mongoc_collection_insert_bulk() | MAND | | | 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_COM- | MONGOC_ERROR_SERVER | | | MAND | | +-----------------------------------------------+--------------------+---------------------+ | Write-concern timeout | MONGOC_ER- | MONGOC_ER- | | | ROR_WRITE_CONCERN | ROR_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 2009-present, MongoDB, Inc. 1.30.2 Apr 12, 2025 MONGOC_ERRORS(3)
DESCRIPTION | ERROR LABELS | SETTING THE ERROR API VERSION | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mongoc_errors&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>