1MONGOC_ERRORS(3) libmongoc MONGOC_ERRORS(3)
2
6 mongoc_errors - Error Reporting « index
7
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 SEE ALSO:
16 Handling Errors in libbson.
17 ┌────────────────────┬──────────────────────────────────┬────────────────────────┐
20 │Domain │ Code │ Description │
21 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
22 │MONGOC_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 │ │ 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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
75 │MONGOC_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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
86 │MONGOC_ERROR_PROTO‐ │ MONGOC_ERROR_PROTO‐ │ Corrupt response │
87 │COL │ 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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
94 │MONGOC_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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
111 │MONGOC_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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
117 │MONGOC_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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
123 │MONGOC_ERROR_SASL │ A SASL error code. │ man sasl_errors for a │
124 │ │ │ list of codes. │
125 └────────────────────┴──────────────────────────────────┴────────────────────────┘
126 │MONGOC_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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
142 │MONGOC_ERROR_NAME‐ │ MONGOC_ERROR_NAME‐ │ You tried to create a │
143 │SPACE │ SPACE_INVALID │ collection with an in‐ │
144 │ │ │ valid name. │
145 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
146 │MONGOC_ERROR_COM‐ │ MONGOC_ERROR_COMMAND_IN‐ │ Many functions set │
147 │MAND │ 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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
175 │MONGOC_ERROR_COM‐ │ Error code from server. │ Error API Version 1: │
176 │MAND │ │ Server error from a │
177 │ │ │ command. The server │
178 │ │ │ error message is in │
179 │ │ │ message. │
180 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
181 │MONGOC_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 │MONGOC_ERROR_COL‐ │ MONGOC_ERROR_COLLEC‐ │ Invalid or empty input │
200 │LECTION │ 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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
213 │MONGOC_ERROR_COL‐ │ Error code from server. │ Error API Version 1: │
214 │LECTION │ │ 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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
224 │MONGOC_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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
235 │MONGOC_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 │ │ 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 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
272 │MONGOC_ERROR_SCRAM │ MONGOC_ERROR_SCRAM_PROTOCOL_ER‐ │ Failure in SCRAM-SHA-1 │
273 │ │ ROR │ authentication. │
274 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
275 │MONGOC_ER‐ │ MONGOC_ERROR_SERVER_SELEC‐ │ No replica set member │
276 │ROR_SERVER_SELEC‐ │ TION_FAILURE │ or mongos is avail‐ │
277 │TION │ │ able, or none matches │
278 │ │ │ your read preference, │
279 │ │ │ or you supplied an in‐ │
280 │ │ │ valid mon‐ │
281 │ │ │ goc_read_prefs_t. │
282 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
283 │MONGOC_ER‐ │ Error code from server. │ There was a write con‐ │
284 │ROR_WRITE_CONCERN │ │ cern error or timeout │
285 │ │ │ from the server. │
286 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
287 │MONGOC_ERROR_TRANS‐ │ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start │
288 │ACTION │ │ a transaction when one │
289 │ │ │ is already in │
290 │ │ │ progress, or commit or │
291 │ │ │ abort when there is no │
292 │ │ │ transaction. │
293 ├────────────────────┼──────────────────────────────────┼────────────────────────┤
294 │MONGOC_ER‐ │ Error code produced by libmon‐ │ An error occurred in │
295 │ROR_CLIENT_SIDE_EN‐ │ gocrypt. │ the library responsi‐ │
296 │CRYPTION │ │ ble for Client Side │
297 │ │ │ Encryption │
298 └────────────────────┴──────────────────────────────────┴────────────────────────┘
299
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 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 { "errorLabels": [ "TransientTransactionError" ] }
312 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 The following error labels are currently defined. Future versions of
318 MongoDB may introduce new labels.
319 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 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
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 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 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 ┌──────────────────────┬────────────────────┬─────────────────────┐
358 │Error Source │ API Version 1 │ API Version 2 │
359 ├──────────────────────┼────────────────────┼─────────────────────┤
360 │mongoc_cursor_error │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
361 ├──────────────────────┼────────────────────┼─────────────────────┤
362 │mongoc_client_com‐ │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
363 │mand_with_opts, │ │ │
364 │mongoc_data‐ │ │ │
365 │base_com‐ │ │ │
366 │mand_with_opts, and │ │ │
367 │other command func‐ │ │ │
368 │tions │ │ │
369 ├──────────────────────┼────────────────────┼─────────────────────┤
370 │mongoc_collec‐ │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
371 │tion_count_with_opts │ │ │
372 │mon‐ │ │ │
373 │goc_client_get_data‐ │ │ │
374 │base_names_with_opts, │ │ │
375 │and other command │ │ │
376 │helper functions │ │ │
377 ├──────────────────────┼────────────────────┼─────────────────────┤
378 │mongoc_collection_in‐ │ MONGOC_ERROR_COM‐ │ MONGOC_ERROR_SERVER │
379 │sert_one mongoc_col‐ │ MAND │ │
380 │lection_insert_bulk │ │ │
381 │mongoc_collection_up‐ │ │ │
382 │date_one mongoc_col‐ │ │ │
383 │lection_update_many │ │ │
384 │mongoc_collection_re‐ │ │ │
385 │place_one mongoc_col‐ │ │ │
386 │lection_delete_one │ │ │
387 │mongoc_collec‐ │ │ │
388 │tion_delete_many │ │ │
389 ├──────────────────────┼────────────────────┼─────────────────────┤
390 │mongoc_bulk_opera‐ │ MONGOC_ERROR_COM‐ │ MONGOC_ERROR_SERVER │
391 │tion_execute │ MAND │ │
392 ├──────────────────────┼────────────────────┼─────────────────────┤
393 │Write-concern timeout │ MONGOC_ER‐ │ MONGOC_ER‐ │
394 │ │ ROR_WRITE_CONCERN │ ROR_WRITE_CONCERN │
395 └──────────────────────┴────────────────────┴─────────────────────┘
396 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 SEE ALSO:
402 MongoDB Server Error Codes
403
406 MongoDB, Inc
407
409 2017-present, MongoDB, Inc
4101.20.0 Nov 18, 2021 MONGOC_ERRORS(3)