Provided by: libmongoc-doc_1.15.0-1_all bug

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.

┌──────────────────────────────┬────────────────────────────────────────────┬──────────────────────────────────────────┐
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_CLIENTMONGOC_ERROR_CLIENT_TOO_BIG                │ You   tried  to  send  a                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_CLIENT_AUTHENTICATE           │ Wrong   credentials,  or                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER     │ You    tried    an   SSL                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_CLIENT_IN_EXHAUST             │ You began  iterating  an                 │
│                              │                                            │ mongoc_client_t.                         │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_CLIENT_SESSION_FAILURE        │ Failure    related    to                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_STREAMMONGOC_ERROR_STREAM_NAME_RESOLUTION        │ DNS failure.                             │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_STREAM_SOCKET                 │ Timeout    communicating                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_STREAM_CONNECT                │ Failed  to  connect   to                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_PROTOCOLMONGOC_ERROR_PROTOCOL_INVALID_REPLY        │ Corrupt   response  from                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION     │ The  server  version  is                 │
└──────────────────────────────┴────────────────────────────────────────────┴──────────────────────────────────────────┘

│MONGOC_ERROR_CURSORMONGOC_ERROR_CURSOR_INVALID_CURSOR         │ You passed bad arguments                 │
│                              │                                            │ mongoc_collection_find_with_opts,        │
│                              │                                            │ mongoc_cursor_next  on a                 │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN │ A  resume  token was not returned        │
│                              │                                            │ mongoc_change_stream_next                │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_QUERYMONGOC_ERROR_QUERY_FAILUREError API Version 1: Server error        │
│                              │                                            │ error message is in message.             │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SERVERMONGOC_ERROR_QUERY_FAILUREError API Version 2: Server error        │
│                              │                                            │ error message is in message.             │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SASL             │ A SASL error code.                         │ man  sasl_errors  for  a  list of        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_BSONMONGOC_ERROR_BSON_INVALID                  │ You   passed   an   invalid    or        │
│                              │                                            │ mongoc_collection_create_index           │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_NAMESPACEMONGOC_ERROR_NAMESPACE_INVALID             │ You  tried to create a collection        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_COMMANDMONGOC_ERROR_COMMAND_INVALID_ARG           │ Many  functions  set  this  error        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION     │ You tried to use a command option        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_DUPLICATE_KEY                 │ An  insert   or   update   failed        │
│                              │                                            │ _id   or    other    unique-index        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_MAX_TIME_MS_EXPIRED           │ The   operation   failed  because        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ MONGOC_ERROR_SERVER_SELECTION_INVALID_ID   │ The  serverId   option   for   an        │
│                              │                                            │ (denoted   by    the    sessionId        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_COMMANDError code from server.                    │ Error API Version 1: Server error        │
│                              │                                            │ message is in message.                   │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SERVERError code from server.                    │ Error API Version 2: Server error        │
│                              │                                            │ message is in message.                   │
└──────────────────────────────┴────────────────────────────────────────────┴──────────────────────────────────────────┘

│MONGOC_ERROR_COLLECTIONMONGOC_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_COLLECTIONError code from server.                    │ Error API Version 1: Server error        │
│                              │                                            │ 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_SERVERError code from server.                    │ Error API Version 2: Server error        │
│                              │                                            │ 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_GRIDFSMONGOC_ERROR_GRIDFS_CHUNK_MISSING          │ The  GridFS  file  is  missing  a        │
│                              │                                            │ document     in     its    chunks        │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│                              │ 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_SCRAMMONGOC_ERROR_SCRAM_PROTOCOL_ERROR          │ Failure in SCRAM-SHA-1 authentication.   │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_SERVER_SELECTIONMONGOC_ERROR_SERVER_SELECTION_FAILURE      │ No  replica  set  member  or  mongos  is │
│                              │                                            │ mongoc_read_prefs_t.                     │
├──────────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────┤
│MONGOC_ERROR_WRITE_CONCERNError code from server.                    │ There  was  a  write  concern  error  or │
└──────────────────────────────┴────────────────────────────────────────────┴──────────────────────────────────────────┘

│MONGOC_ERROR_TRANSACTIONMONGOC_ERROR_TRANSACTION_INVALID           │ You attempted  to  start  a  transaction │
└──────────────────────────────┴────────────────────────────────────────────┴──────────────────────────────────────────┘

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_errorMONGOC_ERROR_QUERYMONGOC_ERROR_SERVER        │
 └────────────────────────────────────────────┴────────────────────────────┴────────────────────────────┘

 │mongoc_client_command_with_opts,            │ MONGOC_ERROR_QUERYMONGOC_ERROR_SERVER        │
 │mongoc_database_command_with_opts,          │                            │                            │
 │and     other    command                    │                            │                            │
 │functions                                   │                            │                            │
 ├────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
 │mongoc_collection_count_with_optsMONGOC_ERROR_QUERYMONGOC_ERROR_SERVER        │
 │mongoc_client_get_database_names_with_opts, │                            │                            │
 │and other command helper functions          │                            │                            │
 ├────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
 │mongoc_collection_insert_oneMONGOC_ERROR_COMMANDMONGOC_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_executeMONGOC_ERROR_COMMANDMONGOC_ERROR_SERVER        │
 ├────────────────────────────────────────────┼────────────────────────────┼────────────────────────────┤
 │Write-concern timeout                       │ MONGOC_ERROR_WRITE_CONCERNMONGOC_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