1MONGOC_ERRORS(3)                   libmongoc                  MONGOC_ERRORS(3)
2
3
4
5« libmongoc
6

DESCRIPTION

8       Many  C  Driver  functions  report  errors by returning false or -1 and
9       filling out a bson_error_t structure with an error domain, error  code,
10       and  message. Use domain to determine which subsystem generated the er‐
11       ror, and code for the specific error. message is a human-readable error
12       description.
13
14       SEE ALSO:
15          Handling Errors in libbson.
16
17
18┌────────────────────┬──────────────────────────────────┬────────────────────────────────────────────┐
19│Code                │ Description                      │                                            │
20├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
21MONGOC_ERROR_CLIENT MONGOC_ER‐                       │ You tried to send a                        │
22│                    │ ROR_CLIENT_TOO_BIG               │ message larger than                        │
23│                    │                                  │ the  server's   max                        │
24│                    │                                  │ message size.                              │
25├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
26│                    │ MONGOC_ER‐                       │ Wrong  credentials,                        │
27│                    │ ROR_CLIENT_AUTHEN‐               │ or failure  sending                        │
28│                    │ TICATE                           │ or   receiving  au‐                        │
29│                    │                                  │ thentication   mes‐                        │
30│                    │                                  │ sages.                                     │
31├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
32│                    │ MONGOC_ER‐                       │ You  tried  an  TLS                        │
33│                    │ ROR_CLIENT_NO_AC‐                │ connection but  the                        │
34│                    │ CEPTABLE_PEER                    │ driver    was   not                        │
35│                    │                                  │ built with TLS.                            │
36├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
37│                    │ MONGOC_ER‐                       │ You began iterating                        │
38│                    │ ROR_CLIENT_IN_EX‐                │ an  exhaust cursor,                        │
39│                    │ HAUST                            │ then tried to begin                        │
40│                    │                                  │ another   operation                        │
41│                    │                                  │ with    the    same                        │
42│                    │                                  │ mongoc_client_t.                           │
43├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
44│                    │ MONGOC_ER‐                       │ Failure  related to                        │
45│                    │ ROR_CLIENT_SES‐                  │ creating or using a                        │
46│                    │ SION_FAILURE                     │ logical session.                           │
47├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
48│                    │ MONGOC_ER‐                       │ Failure related  to                        │
49│                    │ ROR_CLIENT_IN‐                   │ arguments    passed                        │
50│                    │ VALID_ENCRYP‐                    │ when   initializing                        │
51│                    │ TION_ARG                         │ In-Use Encryption.                         │
52├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
53│                    │ MONGOC_ER‐                       │ Failure related  to                        │
54│                    │ ROR_CLIENT_IN‐                   │ In-Use Encryption.                         │
55│                    │ VALID_ENCRYP‐                    │                                            │
56│                    │ TION_STATE                       │                                            │
57├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
58│                    │ MONGOC_ER‐                       │ You   attempted  to                        │
59│                    │ ROR_CLIENT_IN‐                   │ connect to  a  Mon‐                        │
60│                    │ VALID_LOAD_BALANCER              │ goDB  server behind                        │
61│                    │                                  │ a  load   balancer,                        │
62│                    │                                  │ but the server does                        │
63│                    │                                  │ not advertize  load                        │
64│                    │                                  │ balanced support.                          │
65└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
66
67MONGOC_ERROR_STREAM MONGOC_ER‐                       │ DNS failure.                               │
68│                    │ ROR_STREAM_NAME_RES‐             │                                            │
69│                    │ OLUTION                          │                                            │
70├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
71│                    │ MONGOC_ER‐                       │ Timeout communicat‐                        │
72│                    │ ROR_STREAM_SOCKET                │ ing with server, or                        │
73│                    │                                  │ connection closed.                         │
74├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
75│                    │ MONGOC_ER‐                       │ Failed  to  connect                        │
76│                    │ ROR_STREAM_CONNECT               │ to server.                                 │
77├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
78MONGOC_ERROR_PROTO‐ MONGOC_ERROR_PROTO‐              │ Corrupt    response                        │
79COL                 COL_INVALID_REPLY                │ from server.                               │
80├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
81│                    │ MONGOC_ERROR_PROTO‐              │ The server  version                        │
82│                    │ COL_BAD_WIRE_VERSION             │ is  too  old or too                        │
83│                    │                                  │ new to  communicate                        │
84│                    │                                  │ with the driver.                           │
85├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
86MONGOC_ERROR_CURSOR MONGOC_ERROR_CUR‐                │ You passed bad  ar‐                        │
87│                    │ SOR_INVALID_CURSOR               │ guments          to                        │
88│                    │                                  │ mongoc_collection_find_with_opts(),        │
89│                    │                                  │ or    you    called                        │
90│                    │                                  │ mongoc_cursor_next()
91│                    │                                  │ on  a  completed or                        │
92│                    │                                  │ failed  cursor,  or                        │
93│                    │                                  │ the   cursor  timed                        │
94│                    │                                  │ out on the server.                         │
95├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
96│                    │ MONGOC_ER‐                       │ A resume token was not returned  in        │
97│                    │ ROR_CHANGE_STREAM_NO_RE‐         │ a      document      found     with        │
98│                    │ SUME_TOKEN                       mongoc_change_stream_next()
99├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
100MONGOC_ERROR_QUERY  MONGOC_ERROR_QUERY_FAIL‐         Error  API  Version 1: Server error        │
101│                    │ URE                              │ from command or query.  The  server        │
102│                    │                                  │ error message is in message.               │
103├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
104MONGOC_ERROR_SERVER MONGOC_ERROR_QUERY_FAIL‐         Error API Version 2:  Server  error        │
105│                    │ URE                              │ from  command  or query. The server        │
106│                    │                                  │ error message is in message.               │
107├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
108MONGOC_ERROR_SASL   │ A SASL error code.               │ man  sasl_errors  for  a  list   of        │
109│                    │                                  │ codes.                                     │
110├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
111MONGOC_ERROR_BSON   MONGOC_ERROR_BSON_IN‐            │ You passed an invalid or  oversized        │
112│                    │ VALID                            │ BSON  document  as  a parameter, or        │
113│                    │                                  │ called                                     │
114│                    │                                  │ mongoc_collection_create_index()
115│                    │                                  │ with invalid keys,  or  the  server        │
116│                    │                                  │ reply was corrupt.                         │
117├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
118MONGOC_ERROR_NAME‐  MONGOC_ERROR_NAME‐               │ You  tried  to  create a collection        │
119SPACE               SPACE_INVALID                    │ with an invalid name.                      │
120├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
121MONGOC_ERROR_COM‐   MONGOC_ERROR_COMMAND_IN‐         │ Many functions set this error  code        │
122MAND                VALID_ARG                        │ when  passed  bad parameters. Print        │
123│                    │                                  │ the error message for details.             │
124├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
125│                    │ MONGOC_ERROR_PROTO‐              │ You  tried  to use a command option        │
126│                    │ COL_BAD_WIRE_VERSION             │ the server does not support.               │
127├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
128│                    │ MONGOC_ERROR_DUPLI‐              │ An  insert or update failed because        │
129│                    │ CATE_KEY                         │ because of a duplicate _id or other        │
130│                    │                                  │ unique-index violation.                    │
131└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
132
133│                    │ MONGOC_ER‐                       │ The operation failed  because  max‐        │
134│                    │ ROR_MAX_TIME_MS_EXPIRED          │ TimeMS expired.                            │
135├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
136│                    │ MONGOC_ERROR_SERVER_SE‐          │ The serverId option for  an  opera‐        │
137│                    │ LECTION_INVALID_ID               │ tion   conflicts  with  the  pinned        │
138│                    │                                  │ server for that operation's  client        │
139│                    │                                  │ session  (denoted  by the sessionId        
140│                    │                                  │ option).                                   │
141├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
142MONGOC_ERROR_COM‐   Error code from server.          │ Error  API  Version 1: Server error        │
143MAND                │                                  │ from a command.  The  server  error        │
144│                    │                                  │ message is in message.                     │
145├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
146MONGOC_ERROR_SERVER Error code from server.          │ Error  API  Version 2: Server error        │
147│                    │                                  │ from a command.  The  server  error        │
148│                    │                                  │ message is in message.                     │
149├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
150MONGOC_ERROR_COL‐   MONGOC_ERROR_COLLEC‐             │ Invalid    or    empty   input   to        │
151LECTION             TION_INSERT_FAILED, MON‐         mongoc_collection_insert_one(),            │
152│                    │ GOC_ERROR_COLLECTION_UP‐         mongoc_collection_insert_bulk(),           │
153│                    │ DATE_FAILED,  MONGOC_ER‐         mongoc_collection_update_one(),            │
154│                    │ ROR_COLLEC‐                      mongoc_collection_update_many(),           │
155│                    │ TION_DELETE_FAILED.              │ mongoc_collection_replace_one(),           │
156│                    │                                  │ mongoc_collection_delete_one(),  or        │
157│                    │                                  │ mongoc_collection_delete_many().           │
158├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
159MONGOC_ERROR_COL‐   Error code from server.          │ Error  API  Version 1: Server error        │
160LECTION             │                                  │ from                                       │
161│                    │                                  │ mongoc_collection_insert_one(),            │
162│                    │                                  │ mongoc_collection_insert_bulk(),           │
163│                    │                                  │ mongoc_collection_update_one(),            │
164│                    │                                  │ mongoc_collection_update_many(),           │
165│                    │                                  │ mongoc_collection_replace_one(),           │
166├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
167MONGOC_ERROR_SERVER Error code from server.          │ Error  API  Version 2: Server error        │
168│                    │                                  │ from                                       │
169│                    │                                  │ mongoc_collection_insert_one(),            │
170│                    │                                  │ mongoc_collection_insert_bulk(),           │
171│                    │                                  │ mongoc_collection_update_one(),            │
172│                    │                                  │ mongoc_collection_update_many(),           │
173│                    │                                  │ mongoc_collection_replace_one(),           │
174├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
175MONGOC_ERROR_GRIDFS MONGOC_ER‐                       │ The GridFS file is missing a  docu‐        │
176│                    │ ROR_GRIDFS_CHUNK_MISSING         │ ment in its chunks collection.             │
177├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
178│                    │ MONGOC_ERROR_GRIDFS_COR‐         │ A data inconsistency  was  detected        │
179│                    │ RUPT                             │ in GridFS.                                 │
180├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
181│                    │ MONGOC_ERROR_GRIDFS_IN‐          │ You  passed  a  NULL  filename   to        │
182│                    │ VALID_FILENAME                   mongoc_gridfs_remove_by_filename().        │
183├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
184│                    │ MONGOC_ERROR_GRIDFS_PRO‐         │ You                          called        │
185│                    │ TOCOL_ERROR                      mongoc_gridfs_file_set_id()   after        │
186│                    │                                  │ mongoc_gridfs_file_save(), or tried        │
187│                    │                                  │ to write on a closed GridFS stream.        │
188├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
189│                    │ MONGOC_ER‐                       │ A GridFS file is missing from files        
190│                    │ ROR_GRIDFS_BUCKET_FILE_NOT_FOUND │ collection.                                │
191├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
192│                    │ MONGOC_ER‐                       │ An  error occurred on a stream cre‐        │
193│                    │ ROR_GRIDFS_BUCKET_STREAM         │ ated from a GridFS  operation  like        │
194│                    │                                  │ mongoc_gridfs_bucket_upload_from_stream(). │
195└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
196
197
198
199MONGOC_ERROR_SCRAM  MONGOC_ERROR_SCRAM_PROTOCOL_ER‐  │ Failure in SCRAM-SHA-1 authentication.     │
200│                    │ ROR                              │                                            │
201├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
202MONGOC_ER‐          MONGOC_ERROR_SERVER_SELEC‐       │ No replica set member or mongos is  avail‐ │
203ROR_SERVER_SELEC‐   TION_FAILURE                     │ able,  or  none  matches your read prefer‐
204TION                │                                  │ ence,   or   you   supplied   an   invalid │
205│                    │                                  │ mongoc_read_prefs_t.                       │
206├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
207MONGOC_ER‐          Error code from server.          │ There was a write concern error or timeout
208ROR_WRITE_CONCERN   │                                  │ from the server.                           │
209├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
210MONGOC_ERROR_TRANS‐ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start a transaction  when │
211ACTION              │                                  │ one  is  already in progress, or commit or │
212│                    │                                  │ abort when there is no transaction.        │
213├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
214MONGOC_ER‐          │ Error code produced  by  libmon‐ │ An error occurred in the library responsi‐ │
215ROR_CLIENT_SIDE_EN‐ │ gocrypt.                         │ ble for In-Use Encryption                  │
216CRYPTION            │                                  │                                            │
217├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
218MONGOC_ERROR_AZURE  MONGOC_ERROR_KMS_SERVER_HTTP     │ An Azure HTTP service  responded  with  an │
219│                    │                                  │ error status                               │
220├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
221│                    │ MONGOC_ERROR_KMS_SERVER_BAD_JSON │ An  Azure  service  responded with invalid │
222│                    │                                  │ JSON data                                  │
223├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
224MONGOC_ERROR_GCP    MONGOC_ERROR_KMS_SERVER_HTTP     │ A GCP HTTP service responded with an error │
225│                    │                                  │ status                                     │
226├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
227│                    │ MONGOC_ERROR_KMS_SERVER_BAD_JSON │ A  GCP service responded with invalid JSON │
228│                    │                                  │ data                                       │
229└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
230

ERROR LABELS

232       In some cases your application must make decisions based on what  cate‐
233       gory of error the driver has returned, but these categories do not cor‐
234       respond perfectly to an error domain or code. In such cases, error  la‐
235       bels  provide  a  reliable way to determine how your application should
236       respond to an error.
237
238       Any C Driver function that has a bson_t out-parameter named  reply  may
239       include  error  labels  to the reply, in the form of a BSON field named
240       "errorLabels" containing an array of strings:
241
242          { "errorLabels": [ "TransientTransactionError" ] }
243
244       Use mongoc_error_has_label() to test if a reply contains a specific la‐
245       bel.  See  mongoc_client_session_start_transaction()  for  example code
246       that demonstrates the use of error labels in application logic.
247
248       The following error labels are currently defined.  Future  versions  of
249       MongoDB may introduce new labels.
250
251   TransientTransactionError
252       Within  a  multi-document  transaction,  certain  errors  can leave the
253       transaction in an unknown or aborted state. These  include  write  con‐
254       flicts,  primary stepdowns, and network errors. In response, the appli‐
255       cation should abort the transaction and try the same sequence of opera‐
256       tions again in a new transaction.
257
258   UnknownTransactionCommitResult
259       When  mongoc_client_session_commit_transaction()  encounters  a network
260       error or certain server errors, it is not known whether the transaction
261       was  committed.  Applications  should attempt to commit the transaction
262       again until: the commit succeeds, the commit fails with  an  error  not
263       labeled "UnknownTransactionCommitResult", or the application chooses to
264       give up.
265

SETTING THE ERROR API VERSION

267       The driver's error reporting began with a design flaw: when  the  error
268       domain  is  MONGOC_ERROR_COLLECTION,  MONGOC_ERROR_QUERY, or MONGOC_ER‐
269       ROR_COMMAND, the error code might originate  from  the  server  or  the
270       driver.  An  application  cannot always know where an error originated,
271       and therefore cannot tell what the code means.
272
273       For example, if mongoc_collection_update_one() sets the error's  domain
274       to  MONGOC_ERROR_COLLECTION  and its code to 24, the application cannot
275       know whether 24 is the generic driver error  code  MONGOC_ERROR_COLLEC‐
276       TION_UPDATE_FAILED or the specific server error code "LockTimeout".
277
278       To  fix this flaw while preserving backward compatibility, the C Driver
279       1.4 introduces "Error API Versions". Version 1, the default  Error  API
280       Version,  maintains the flawed behavior. Version 2 adds a new error do‐
281       main, MONGOC_ERROR_SERVER. In Version 2, error codes originating on the
282       server  always  have  error  domain  MONGOC_ERROR_SERVER  or MONGOC_ER‐
283       ROR_WRITE_CONCERN. When the driver uses Version 2 the  application  can
284       always  determine  the  origin and meaning of error codes. New applica‐
285       tions should use Version 2, and existing applications should be updated
286       to use Version 2 as well.
287
288┌──────────────────────────────────────────────┬────────────────────┬─────────────────────┐
289│Error Source                                  │ API Version 1      │ API Version 2       │
290├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
291mongoc_cursor_error()MONGOC_ERROR_QUERY MONGOC_ERROR_SERVER 
292├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
293mongoc_client_command_with_opts(),            │ MONGOC_ERROR_QUERY MONGOC_ERROR_SERVER 
294mongoc_database_command_with_opts(),          │                    │                     │
295│and   other   command                         │                    │                     │
296│functions                                     │                    │                     │
297├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
298mongoc_collection_count_with_opts()MONGOC_ERROR_QUERY MONGOC_ERROR_SERVER 
299mongoc_client_get_database_names_with_opts(), │                    │                     │
300│and other command helper functions            │                    │                     │
301├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
302mongoc_collection_insert_one()MONGOC_ERROR_COM‐  MONGOC_ERROR_SERVER 
303mongoc_collection_insert_bulk()MAND               │                     │
304mongoc_collection_update_one()                │                    │                     │
305mongoc_collection_update_many()               │                    │                     │
306mongoc_collection_replace_one()               │                    │                     │
307mongoc_collection_delete_one()                │                    │                     │
308mongoc_collection_delete_many()               │                    │                     │
309├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
310mongoc_bulk_operation_execute()MONGOC_ERROR_COM‐  MONGOC_ERROR_SERVER 
311│                                              │ MAND               │                     │
312├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
313│Write-concern timeout                         │ MONGOC_ER‐         MONGOC_ER‐          
314│                                              │ ROR_WRITE_CONCERN  ROR_WRITE_CONCERN   
315└──────────────────────────────────────────────┴────────────────────┴─────────────────────┘
316
317       The Error API Versions are defined with MONGOC_ERROR_API_VERSION_LEGACY
318       and    MONGOC_ERROR_API_VERSION_2.     Set     the     version     with
319       mongoc_client_set_error_api() or mongoc_client_pool_set_error_api().
320
321       SEE ALSO:
322          MongoDB Server Error Codes
323
324

AUTHOR

326       MongoDB, Inc
327
329       2017-present, MongoDB, Inc
330
331
332
333
3341.25.1                           Nov 08, 2023                 MONGOC_ERRORS(3)
Impressum