1MONGOC_ERRORS(3)                   libmongoc                  MONGOC_ERRORS(3)
2
3
4

NAME

6       mongoc_errors - Error Reporting « index
7

DESCRIPTION

9       Many  C  Driver  functions  report  errors by returning false or -1 and
10       filling out a bson_error_t structure with an error domain, error  code,
11       and  message. Use domain to determine which subsystem generated the er‐
12       ror, and code for the specific error. message is a human-readable error
13       description.
14
15       SEE ALSO:
16          Handling Errors in libbson.
17
18
19  ┌────────────────────┬──────────────────────────────────┬────────────────────────┐
20  │Domain              │ Code                             │ Description            │
21  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
22MONGOC_ERROR_CLIENT MONGOC_ER‐                       │ You tried to send a    │
23  │                    │ ROR_CLIENT_TOO_BIG               │ message larger than    │
24  │                    │                                  │ the  server's   max    │
25  │                    │                                  │ message size.          │
26  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
27  │                    │ MONGOC_ER‐                       │ Wrong  credentials,    │
28  │                    │ ROR_CLIENT_AUTHEN‐               │ or failure  sending    │
29  │                    │ TICATE                           │ or   receiving  au‐    │
30  │                    │                                  │ thentication   mes‐    │
31  │                    │                                  │ sages.                 │
32  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
33  │                    │ MONGOC_ER‐                       │ You  tried  an  TLS    │
34  │                    │ ROR_CLIENT_NO_AC‐                │ connection but  the    │
35  │                    │ CEPTABLE_PEER                    │ driver    was   not    │
36  │                    │                                  │ built with TLS.        │
37  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
38  │                    │ MONGOC_ER‐                       │ You began iterating    │
39  │                    │ ROR_CLIENT_IN_EX‐                │ an  exhaust cursor,    │
40  │                    │ HAUST                            │ then tried to begin    │
41  │                    │                                  │ another   operation    │
42  │                    │                                  │ with the same  mon‐    
43  │                    │                                  │ goc_client_t.          │
44  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
45  │                    │ MONGOC_ER‐                       │ Failure  related to    │
46  │                    │ ROR_CLIENT_SES‐                  │ creating or using a    │
47  │                    │ SION_FAILURE                     │ logical session.       │
48  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
49  │                    │ MONGOC_ER‐                       │ Failure related  to    │
50  │                    │ ROR_CLIENT_IN‐                   │ arguments    passed    │
51  │                    │ VALID_ENCRYP‐                    │ when   initializing    │
52  │                    │ TION_ARG                         │ Client-Side   Field    │
53  │                    │                                  │ Level Encryption.      │
54  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
55  │                    │ MONGOC_ER‐                       │ Failure  related to    │
56  │                    │ ROR_CLIENT_IN‐                   │ Client-Side   Field    │
57  │                    │ VALID_ENCRYP‐                    │ Level Encryption.      │
58  │                    │ TION_STATE                       │                        │
59  └────────────────────┴──────────────────────────────────┴────────────────────────┘
60
61
62
63
64
65
66
67  │                    │ MONGOC_ER‐                       │ You   attempted  to    │
68  │                    │ ROR_CLIENT_IN‐                   │ connect to  a  Mon‐    │
69  │                    │ VALID_LOAD_BALANCER              │ goDB  server behind    │
70  │                    │                                  │ a  load   balancer,    │
71  │                    │                                  │ but the server does    │
72  │                    │                                  │ not advertize  load    │
73  │                    │                                  │ balanced support.      │
74  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
75MONGOC_ERROR_STREAM MONGOC_ER‐                       │ DNS failure.           │
76  │                    │ ROR_STREAM_NAME_RES‐             │                        │
77  │                    │ OLUTION                          │                        │
78  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
79  │                    │ MONGOC_ER‐                       │ Timeout communicat‐    │
80  │                    │ ROR_STREAM_SOCKET                │ ing with server, or    │
81  │                    │                                  │ connection closed.     │
82  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
83  │                    │ MONGOC_ER‐                       │ Failed  to  connect    │
84  │                    │ ROR_STREAM_CONNECT               │ to server.             │
85  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
86MONGOC_ERROR_PROTO‐ MONGOC_ERROR_PROTO‐              │ Corrupt    response    │
87COL                 COL_INVALID_REPLY                │ from server.           │
88  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
89  │                    │ MONGOC_ERROR_PROTO‐              │ The server  version    │
90  │                    │ COL_BAD_WIRE_VERSION             │ is  too  old or too    │
91  │                    │                                  │ new to  communicate    │
92  │                    │                                  │ with the driver.       │
93  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
94MONGOC_ERROR_CURSOR MONGOC_ERROR_CUR‐                │ You passed bad  ar‐    │
95  │                    │ SOR_INVALID_CURSOR               │ guments   to   mon‐    
96  │                    │                                  │ goc_collec‐            
97  │                    │                                  │ tion_find_with_opts,   │
98  │                    │                                  │ or you called  mon‐    
99  │                    │                                  │ goc_cursor_next  on    │
100  │                    │                                  │ a   completed    or    │
101  │                    │                                  │ failed  cursor,  or    │
102  │                    │                                  │ the  cursor   timed    │
103  │                    │                                  │ out on the server.     │
104  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
105  │                    │ MONGOC_ER‐                       │ A  resume  token was   │
106  │                    │ ROR_CHANGE_STREAM_NO_RE‐         │ not  returned  in  a   │
107  │                    │ SUME_TOKEN                       │ document  found with   │
108  │                    │                                  │ mon‐                   
109  │                    │                                  │ goc_change_stream_next 
110  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
111MONGOC_ERROR_QUERY  MONGOC_ERROR_QUERY_FAIL‐         Error  API  Version 1: │
112  │                    │ URE                              │ Server error from com‐ │
113  │                    │                                  │ mand   or  query.  The │
114  │                    │                                  │ server  error  message │
115  │                    │                                  │ is in message.         │
116  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
117MONGOC_ERROR_SERVER MONGOC_ERROR_QUERY_FAIL‐         Error API  Version  2: │
118  │                    │ URE                              │ Server error from com‐ │
119  │                    │                                  │ mand  or  query.   The │
120  │                    │                                  │ server  error  message │
121  │                    │                                  │ is in message.         │
122  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
123MONGOC_ERROR_SASL   │ A SASL error code.               │ man sasl_errors for  a │
124  │                    │                                  │ list of codes.         │
125  └────────────────────┴──────────────────────────────────┴────────────────────────┘
126
127
128
129
130
131
132
133MONGOC_ERROR_BSON   MONGOC_ERROR_BSON_IN‐            │ You passed an  invalid │
134  │                    │ VALID                            │ or oversized BSON doc‐ │
135  │                    │                                  │ ument as a  parameter, │
136  │                    │                                  │ or  called mongoc_col‐ 
137  │                    │                                  │ lection_create_index   
138  │                    │                                  │ with  invalid keys, or │
139  │                    │                                  │ the server  reply  was │
140  │                    │                                  │ corrupt.               │
141  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
142MONGOC_ERROR_NAME‐  MONGOC_ERROR_NAME‐               │ You  tried to create a │
143SPACE               SPACE_INVALID                    │ collection with an in‐ │
144  │                    │                                  │ valid name.            │
145  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
146MONGOC_ERROR_COM‐   MONGOC_ERROR_COMMAND_IN‐         │ Many   functions   set │
147MAND                VALID_ARG                        │ this error  code  when │
148  │                    │                                  │ passed bad parameters. │
149  │                    │                                  │ Print the  error  mes‐ │
150  │                    │                                  │ sage for details.      │
151  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
152  │                    │ MONGOC_ERROR_PROTO‐              │ You  tried  to  use  a │
153  │                    │ COL_BAD_WIRE_VERSION             │ command   option   the │
154  │                    │                                  │ server does  not  sup‐ │
155  │                    │                                  │ port.                  │
156  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
157  │                    │ MONGOC_ERROR_DUPLI‐              │ An  insert  or  update │
158  │                    │ CATE_KEY                         │ failed because because │
159  │                    │                                  │ of a duplicate _id  or │
160  │                    │                                  │ other unique-index vi‐ │
161  │                    │                                  │ olation.               │
162  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
163  │                    │ MONGOC_ER‐                       │ The  operation  failed │
164  │                    │ ROR_MAX_TIME_MS_EXPIRED          │ because maxTimeMS  ex‐ │
165  │                    │                                  │ pired.                 │
166  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
167  │                    │ MONGOC_ERROR_SERVER_SE‐          │ The  serverId   option │
168  │                    │ LECTION_INVALID_ID               │ for  an operation con‐ │
169  │                    │                                  │ flicts with the pinned │
170  │                    │                                  │ server for that opera‐ │
171  │                    │                                  │ tion's client  session │
172  │                    │                                  │ (denoted  by  the ses‐ 
173  │                    │                                  │ sionId option).        │
174  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
175MONGOC_ERROR_COM‐   Error code from server.          │ Error  API  Version 1: │
176MAND                │                                  │ Server  error  from  a │
177  │                    │                                  │ command.   The  server │
178  │                    │                                  │ error  message  is  in │
179  │                    │                                  │ message.               │
180  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
181MONGOC_ERROR_SERVER Error code from server.          │ Error  API  Version 2: │
182  │                    │                                  │ Server  error  from  a │
183  │                    │                                  │ command.   The  server │
184  │                    │                                  │ error  message  is  in │
185  │                    │                                  │ message.               │
186  └────────────────────┴──────────────────────────────────┴────────────────────────┘
187
188
189
190
191
192
193
194
195
196
197
198
199MONGOC_ERROR_COL‐   MONGOC_ERROR_COLLEC‐             │ Invalid or empty input │
200LECTION             TION_INSERT_FAILED, MON‐         │ to      mongoc_collec‐ 
201  │                    │ GOC_ERROR_COLLECTION_UP‐         tion_insert_one,  mon‐ 
202  │                    │ DATE_FAILED,  MONGOC_ER‐         goc_collection_in‐     
203  │                    │ ROR_COLLEC‐                      sert_bulk, mongoc_col‐ 
204  │                    │ TION_DELETE_FAILED.              │ lection_update_one,    │
205  │                    │                                  │ mongoc_collection_up‐  
206  │                    │                                  │ date_many, mongoc_col‐ 
207  │                    │                                  │ lection_replace_one,   │
208  │                    │                                  │ mongoc_collec‐         
209  │                    │                                  │ tion_delete_one,    or │
210  │                    │                                  │ mongoc_collec‐         
211  │                    │                                  │ tion_delete_many.      │
212  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
213MONGOC_ERROR_COL‐   Error code from server.          │ Error API  Version  1: │
214LECTION             │                                  │ Server error from mon‐ 
215  │                    │                                  │ goc_collection_in‐     
216  │                    │                                  │ sert_one,  mongoc_col‐ 
217  │                    │                                  │ lection_insert_bulk,   │
218  │                    │                                  │ mongoc_collection_up‐  
219  │                    │                                  │ date_one,  mongoc_col‐ 
220  │                    │                                  │ lection_update_many,   │
221  │                    │                                  │ mongoc_collection_re‐  
222  │                    │                                  │ place_one,             │
223  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
224MONGOC_ERROR_SERVER Error code from server.          │ Error  API  Version 2: │
225  │                    │                                  │ Server error from mon‐ 
226  │                    │                                  │ goc_collection_in‐     
227  │                    │                                  │ sert_one,  mongoc_col‐ 
228  │                    │                                  │ lection_insert_bulk,   │
229  │                    │                                  │ mongoc_collection_up‐  
230  │                    │                                  │ date_one,  mongoc_col‐ 
231  │                    │                                  │ lection_update_many,   │
232  │                    │                                  │ mongoc_collection_re‐  
233  │                    │                                  │ place_one,             │
234  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
235MONGOC_ERROR_GRIDFS MONGOC_ER‐                       │ The   GridFS  file  is │
236  │                    │ ROR_GRIDFS_CHUNK_MISSING         │ missing a document  in │
237  │                    │                                  │ its chunks collection. │
238  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
239  │                    │ MONGOC_ERROR_GRIDFS_COR‐         │ A  data  inconsistency │
240  │                    │ RUPT                             │ was     detected    in │
241  │                    │                                  │ GridFS.                │
242  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
243  │                    │ MONGOC_ERROR_GRIDFS_IN‐          │ You   passed   a  NULL │
244  │                    │ VALID_FILENAME                   │ filename    to    mon‐ 
245  │                    │                                  │ goc_gridfs_re‐         
246  │                    │                                  │ move_by_filename.      │
247  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
248  │                    │ MONGOC_ERROR_GRIDFS_PRO‐         │ You     called    mon‐ 
249  │                    │ TOCOL_ERROR                      goc_gridfs_file_set_id 
250  │                    │                                  │ after             mon‐ 
251  │                    │                                  │ goc_gridfs_file_save,  │
252  │                    │                                  │ or tried to write on a │
253  │                    │                                  │ closed GridFS stream.  │
254  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
255  │                    │ MONGOC_ER‐                       │ A GridFS file is miss‐ │
256  │                    │ ROR_GRIDFS_BUCKET_FILE_NOT_FOUND │ ing from files collec‐ │
257  │                    │                                  │ tion.                  │
258  └────────────────────┴──────────────────────────────────┴────────────────────────┘
259
260
261
262
263
264
265  │                    │ MONGOC_ER‐                       │ An error occurred on a │
266  │                    │ ROR_GRIDFS_BUCKET_STREAM         │ stream created from  a │
267  │                    │                                  │ GridFS  operation like │
268  │                    │                                  │ mon‐                   
269  │                    │                                  │ goc_gridfs_bucket_up‐  
270  │                    │                                  │ load_from_stream.      │
271  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
272MONGOC_ERROR_SCRAM  MONGOC_ERROR_SCRAM_PROTOCOL_ER‐  │ Failure in SCRAM-SHA-1 │
273  │                    │ ROR                              │ authentication.        │
274  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
275MONGOC_ER‐          MONGOC_ERROR_SERVER_SELEC‐       │ No  replica set member │
276ROR_SERVER_SELEC‐   TION_FAILURE                     │ or  mongos  is  avail‐ │
277TION                │                                  │ able,  or none matches │
278  │                    │                                  │ your read  preference, │
279  │                    │                                  │ or you supplied an in‐ │
280  │                    │                                  │ valid             mon‐ 
281  │                    │                                  │ goc_read_prefs_t.      │
282  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
283MONGOC_ER‐          Error code from server.          │ There was a write con‐ │
284ROR_WRITE_CONCERN   │                                  │ cern  error or timeout │
285  │                    │                                  │ from the server.       │
286  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
287MONGOC_ERROR_TRANS‐ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start │
288ACTION              │                                  │ a transaction when one │
289  │                    │                                  │ is      already     in │
290  │                    │                                  │ progress, or commit or │
291  │                    │                                  │ abort when there is no │
292  │                    │                                  │ transaction.           │
293  ├────────────────────┼──────────────────────────────────┼────────────────────────┤
294MONGOC_ER‐          │ Error code produced  by  libmon‐ │ An  error  occurred in │
295ROR_CLIENT_SIDE_EN‐ │ gocrypt.                         │ the library  responsi‐ │
296CRYPTION            │                                  │ ble  for  Client  Side │
297  │                    │                                  │ Encryption             │
298  └────────────────────┴──────────────────────────────────┴────────────────────────┘
299

ERROR LABELS

301       In some cases your application must make decisions based on what  cate‐
302       gory of error the driver has returned, but these categories do not cor‐
303       respond perfectly to an error domain or code. In such cases, error  la‐
304       bels  provide  a  reliable way to determine how your application should
305       respond to an error.
306
307       Any C Driver function that has a bson_t out-parameter named  reply  may
308       include  error  labels  to the reply, in the form of a BSON field named
309       "errorLabels" containing an array of strings:
310
311          { "errorLabels": [ "TransientTransactionError" ] }
312
313       Use mongoc_error_has_label to test if a reply contains a  specific  la‐
314       bel.  See mongoc_client_session_start_transaction for example code that
315       demonstrates the use of error labels in application logic.
316
317       The following error labels are currently defined.  Future  versions  of
318       MongoDB may introduce new labels.
319
320   TransientTransactionError
321       Within  a  multi-document  transaction,  certain  errors  can leave the
322       transaction in an unknown or aborted state. These  include  write  con‐
323       flicts,  primary stepdowns, and network errors. In response, the appli‐
324       cation should abort the transaction and try the same sequence of opera‐
325       tions again in a new transaction.
326
327   UnknownTransactionCommitResult
328       When  mongoc_client_session_commit_transaction encounters a network er‐
329       ror or certain server errors, it is not known whether  the  transaction
330       was  committed.  Applications  should attempt to commit the transaction
331       again until: the commit succeeds, the commit fails with  an  error  not
332       labeled "UnknownTransactionCommitResult", or the application chooses to
333       give up.
334

SETTING THE ERROR API VERSION

336       The driver's error reporting began with a design flaw: when  the  error
337       domain  is  MONGOC_ERROR_COLLECTION,  MONGOC_ERROR_QUERY, or MONGOC_ER‐
338       ROR_COMMAND, the error code might originate  from  the  server  or  the
339       driver.  An  application  cannot always know where an error originated,
340       and therefore cannot tell what the code means.
341
342       For example, if mongoc_collection_update_one sets the error's domain to
343       MONGOC_ERROR_COLLECTION and its code to 24, the application cannot know
344       whether 24 is the generic driver error code MONGOC_ERROR_COLLECTION_UP‐
345       DATE_FAILED or the specific server error code "LockTimeout".
346
347       To  fix this flaw while preserving backward compatibility, the C Driver
348       1.4 introduces "Error API Versions". Version 1, the default  Error  API
349       Version,  maintains the flawed behavior. Version 2 adds a new error do‐
350       main, MONGOC_ERROR_SERVER. In Version 2, error codes originating on the
351       server  always  have  error  domain  MONGOC_ERROR_SERVER  or MONGOC_ER‐
352       ROR_WRITE_CONCERN. When the driver uses Version 2 the  application  can
353       always  determine  the  origin and meaning of error codes. New applica‐
354       tions should use Version 2, and existing applications should be updated
355       to use Version 2 as well.
356
357         ┌──────────────────────┬────────────────────┬─────────────────────┐
358         │Error Source          │ API Version 1      │ API Version 2       │
359         ├──────────────────────┼────────────────────┼─────────────────────┤
360mongoc_cursor_error   MONGOC_ERROR_QUERY MONGOC_ERROR_SERVER 
361         ├──────────────────────┼────────────────────┼─────────────────────┤
362mongoc_client_com‐    MONGOC_ERROR_QUERY MONGOC_ERROR_SERVER 
363mand_with_opts,       │                    │                     │
364mongoc_data‐          │                    │                     │
365base_com‐             │                    │                     │
366mand_with_opts, and   │                    │                     │
367         │other command func‐   │                    │                     │
368         │tions                 │                    │                     │
369         ├──────────────────────┼────────────────────┼─────────────────────┤
370mongoc_collec‐        MONGOC_ERROR_QUERY MONGOC_ERROR_SERVER 
371tion_count_with_opts  │                    │                     │
372mon‐                  │                    │                     │
373goc_client_get_data‐  │                    │                     │
374base_names_with_opts, │                    │                     │
375         │and  other  command   │                    │                     │
376         │helper functions      │                    │                     │
377         ├──────────────────────┼────────────────────┼─────────────────────┤
378mongoc_collection_in‐ MONGOC_ERROR_COM‐  MONGOC_ERROR_SERVER 
379sert_one  mongoc_col‐ MAND               │                     │
380lection_insert_bulk   │                    │                     │
381mongoc_collection_up‐ │                    │                     │
382date_one  mongoc_col‐ │                    │                     │
383lection_update_many   │                    │                     │
384mongoc_collection_re‐ │                    │                     │
385place_one mongoc_col‐ │                    │                     │
386lection_delete_one    │                    │                     │
387mongoc_collec‐        │                    │                     │
388tion_delete_many      │                    │                     │
389         ├──────────────────────┼────────────────────┼─────────────────────┤
390mongoc_bulk_opera‐    MONGOC_ERROR_COM‐  MONGOC_ERROR_SERVER 
391tion_execute          MAND               │                     │
392         ├──────────────────────┼────────────────────┼─────────────────────┤
393         │Write-concern timeout │ MONGOC_ER‐         MONGOC_ER‐          
394         │                      │ ROR_WRITE_CONCERN  ROR_WRITE_CONCERN   
395         └──────────────────────┴────────────────────┴─────────────────────┘
396
397       The Error API Versions are defined with MONGOC_ERROR_API_VERSION_LEGACY
398       and    MONGOC_ERROR_API_VERSION_2.    Set   the   version   with   mon‐
399       goc_client_set_error_api or mongoc_client_pool_set_error_api.
400
401       SEE ALSO:
402          MongoDB Server Error Codes
403
404

AUTHOR

406       MongoDB, Inc
407
409       2017-present, MongoDB, Inc
410
411
412
413
4141.20.0                           Nov 18, 2021                 MONGOC_ERRORS(3)
Impressum