Error Reporting — MongoDB C Driver 1.9.2

- MongoDB C Driver 1.9.2 »
- API Reference

« MongoDB C Driver

# Error Reporting

## 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 SSL connection but the driver was not built with SSL.
| `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_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_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`, `MONGOC_ERROR_COLLECTION_UPDATE_FAILED`, `MONGOC_ERROR_COLLECTION_DELETE_FAILED`. | Invalid or empty input to mongoc_collection_insert_one(), 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_collection_delete_one(), or mongoc_collection_delete_many().
`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_collection_delete_one(), or mongoc_collection_delete_many().
`MONGOC_ERROR_GRIDFS` | `MONGOC_ERROR_GRIDFS_CHUNK_MISSING` | The GridFS file is missing a document in its `chunks` collection.
| `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().
`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 available, or none matches your read preference, or you supplied an invalid mongoc_read_prefs_t.
`MONGOC_ERROR_WRITE_CONCERN` | Error code from server. | There was a write concern error or timeout from the server.

## 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_database_command_with_opts(), and other command functions | `MONGOC_ERROR_QUERY` | `MONGOC_ERROR_SERVER`
mongoc_collection_count_with_opts() mongoc_client_get_database_names_with_opts(), and other command helper functions | `MONGOC_ERROR_QUERY` | `MONGOC_ERROR_SERVER`
mongoc_collection_insert_one() 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_ERROR_COMMAND` | `MONGOC_ERROR_SERVER`
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

Created using Sphinx 1.6.5, based on Sphinx Readable Theme.