.\" This manpage is Copyright (C) 2016 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "ERROR_REPORTING" "3" "2016\(hy10\(hy12" "MongoDB C Driver"
.SH NAME
Error_Reporting \- 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.
.SH "DESCRIPTION"

Many C Driver functions report errors by returning
.B false
or \(hy1 and filling out a
.B bson_error_t
structure with an error domain, error code, and message. Use
.B domain
to determine which subsystem generated the error, and
.B code
for the specific error.
.B message
is a human\(hyreadable error description.

See also:
.B Handling Errors in libbson
.

.TP
.B
.B None
.B MONGOC_ERROR_CLIENT_TOO_BIG
You tried to send a message larger than the server's max message size.
.LP
.TP
.B
.B MONGOC_ERROR_CLIENT_AUTHENTICATE
Wrong credentials, or failure sending or receiving authentication messages.
.LP
.TP
.B
.B MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER
You tried an SSL connection but the driver was not built with SSL.
.LP
.TP
.B
.B MONGOC_ERROR_CLIENT_IN_EXHAUST
You began iterating an exhaust cursor, then tried to begin another operation with the same
.B mongoc_client_t
.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_STREAM_NAME_RESOLUTION
DNS failure.
.LP
.TP
.B
.B MONGOC_ERROR_STREAM_SOCKET
Timeout communicating with server, or connection closed.
.LP
.TP
.B
.B MONGOC_ERROR_STREAM_CONNECT
Failed to connect to server.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_PROTOCOL_INVALID_REPLY
Corrupt response from server.
.LP
.TP
.B
.B MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION
The server version is too old or too new to communicate with the driver.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_CURSOR_INVALID_CURSOR
You passed bad arguments to
.B mongoc_collection_find
, or you called
.B mongoc_cursor_next
on a completed or failed cursor, or the cursor timed out on the server.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_QUERY_FAILURE
.B Error API Version 1
: Server error from command or query. The server error message is in
.B message
.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_QUERY_FAILURE
.B Error API Version 2
: Server error from command or query. The server error message is in
.B message
.
.LP
.TP
.B
.B None
A SASL error code.
.B man sasl_errors
for a list of codes.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_BSON_INVALID
Corrupt server reply, or you called
.B mongoc_collection_create_index
with invalid keys, or tried to insert or update with an invalid document.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_NAMESPACE_INVALID
You tried to create a collection with an invalid name.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_COMMAND_INVALID_ARG
Many functions set this error code when passed bad parameters. Print the error message for details.
.LP
.TP
.B
.B MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION
You tried to use a command option the server does not support.
.LP
.TP
.B
.B None
.B Error code from server
.
.B Error API Version 1
: Server error from a command. The server error message is in
.B message
.
.LP
.TP
.B
.B None
.B Error code from server
.
.B Error API Version 2
: Server error from a command. The server error message is in
.B message
.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_COLLECTION_INSERT_FAILED
,
.B MONGOC_ERROR_COLLECTION_UPDATE_FAILED
,
.B MONGOC_ERROR_COLLECTION_DELETE_FAILED
.
Invalid or empty input to
.B mongoc_collection_insert
,
.B mongoc_collection_insert_bulk
,
.B mongoc_collection_update
, or
.B mongoc_collection_remove
.
.LP
.TP
.B
.B None
.B Error code from server
.
.B Error API Version 1
: Server error from
.B mongoc_collection_insert
,
.B mongoc_collection_insert_bulk
,
.B mongoc_collection_update
, or
.B mongoc_collection_remove
.
.LP
.TP
.B
.B None
.B Error code from server
.
.B Error API Version 2
: Server error from
.B mongoc_collection_insert
,
.B mongoc_collection_insert_bulk
,
.B mongoc_collection_update
, or
.B mongoc_collection_remove
.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_GRIDFS_CHUNK_MISSING
The GridFS file is missing a document in its
.B chunks
collection.
.LP
.TP
.B
.B MONGOC_ERROR_GRIDFS_INVALID_FILENAME
You passed a NULL filename to
.B mongoc_gridfs_remove_by_filename
.
.LP
.TP
.B
.B MONGOC_ERROR_GRIDFS_PROTOCOL_ERROR
You called
.B mongoc_gridfs_file_set_id
after
.B mongoc_gridfs_file_save
.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_SCRAM_PROTOCOL_ERROR
Failure in SCRAM\(hySHA\(hy1 authentication.
.LP
.TP
.B
.B None
.B MONGOC_ERROR_SERVER_SELECTION_FAILURE
No replica set member or mongos is available, or none matches your
.B read preference
, or you supplied an invalid
.B mongoc_read_prefs_t
.
.LP
.TP
.B
.B None
.B Error code from server
.
There was a
.B write concern
error or
.B timeout
from the server.
.LP

.SH "SETTING THE ERROR API VERSION"

The driver's error reporting began with a design flaw: when the error
.B domain
is
.B MONGOC_ERROR_COLLECTION
,
.B MONGOC_ERROR_QUERY
, or
.B MONGOC_ERROR_COMMAND
, the error
.B 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
.B mongoc_collection_update
sets the error's domain to
.B MONGOC_ERROR_COLLECTION
and its code to 24, the application cannot know whether 24 is the generic driver error code
.B 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,
.B MONGOC_ERROR_SERVER
. In Version 2, error codes originating on the server always have error domain
.B MONGOC_ERROR_SERVER
or
.B 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.

.TP
.B

.B mongoc_cursor_error


.B MONGOC_ERROR_QUERY


.B MONGOC_ERROR_SERVER

.LP
.TP
.B
.B mongoc_client_command
,
.B mongoc_database_command
, and other command functions

.B MONGOC_ERROR_QUERY


.B MONGOC_ERROR_SERVER

.LP
.TP
.B
.B mongoc_collection_count_with_opts
,
.B mongoc_client_get_database_names
, and other command helper functions

.B MONGOC_ERROR_QUERY


.B MONGOC_ERROR_SERVER

.LP
.TP
.B

.B mongoc_collection_insert


.B mongoc_collection_insert_bulk


.B mongoc_collection_update


.B mongoc_collection_remove


.B MONGOC_ERROR_COMMAND


.B MONGOC_ERROR_SERVER

.LP
.TP
.B

.nf
mongoc_bulk_operation_execute
.fi


.B MONGOC_ERROR_COMMAND


.B MONGOC_ERROR_SERVER

.LP
.TP
.B
Write\(hyconcern timeout

.B MONGOC_ERROR_WRITE_CONCERN


.B MONGOC_ERROR_WRITE_CONCERN

.LP

The Error API Versions are defined with
.B MONGOC_ERROR_API_VERSION_LEGACY
and
.B MONGOC_ERROR_API_VERSION_2
. Set the version with
.B mongoc_client_set_error_api
or
.B mongoc_client_pool_set_error_api
.

.SH "SEE ALSO"

.B MongoDB Server Error Codes


.B
.SH COLOPHON
This page is part of MongoDB C Driver.
Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.