1MONGOC_ERRORS(3) MongoDB C Driver 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
12 error, and code for the specific error. message is a human-readable
13 error description.
14 See also: Handling Errors in libbson.
16┌────────────────────────┬─────────────────────────────────────────┬───────────────────────────────────────┐
18│Domain │ Code │ Description │
19├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
20│MONGOC_ERROR_CLIENT │ MON‐ │ You tried to send a │
21│ │ GOC_ERROR_CLIENT_TOO_BIG │ message larger than │
22│ │ │ the server's max │
23│ │ │ message size. │
24├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
25│ │ MON‐ │ Wrong credentials, │
26│ │ GOC_ERROR_CLIENT_AUTHEN‐ │ or failure sending │
27│ │ TICATE │ or receiving │
28│ │ │ authentication mes‐ │
29│ │ │ sages. │
30├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
31│ │ MON‐ │ You tried an SSL │
32│ │ GOC_ERROR_CLIENT_NO_ACCEPT‐ │ connection but the │
33│ │ ABLE_PEER │ driver was not │
34│ │ │ built with SSL. │
35├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
36│ │ MON‐ │ You began iterating │
37│ │ GOC_ERROR_CLIENT_IN_EXHAUST │ an exhaust cursor, │
38│ │ │ then tried to begin │
39│ │ │ another operation │
40│ │ │ with the same mon‐ │
41│ │ │ goc_client_t. │
42├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
43│ │ MONGOC_ERROR_CLIENT_SES‐ │ Failure related to │
44│ │ SION_FAILURE │ creating or using a │
45│ │ │ logical session. │
46├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
47│MONGOC_ERROR_STREAM │ MON‐ │ DNS failure. │
48│ │ GOC_ERROR_STREAM_NAME_RESO‐ │ │
49│ │ LUTION │ │
50├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
51│ │ MONGOC_ERROR_STREAM_SOCKET │ Timeout communicat‐ │
52│ │ │ ing with server, or │
53│ │ │ connection closed. │
54├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
55│ │ MONGOC_ERROR_STREAM_CONNECT │ Failed to connect │
56│ │ │ to server. │
57├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
58│MONGOC_ERROR_PROTO‐ │ MONGOC_ERROR_PROTO‐ │ Corrupt response │
59│COL │ COL_INVALID_REPLY │ from server. │
60├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
61│ │ MONGOC_ERROR_PROTO‐ │ The server version │
62│ │ COL_BAD_WIRE_VERSION │ is too old or too │
63│ │ │ new to communicate │
64│ │ │ with the driver. │
65└────────────────────────┴─────────────────────────────────────────┴───────────────────────────────────────┘
66│MONGOC_ERROR_CURSOR │ MONGOC_ERROR_CUR‐ │ You passed bad │
68│ │ SOR_INVALID_CURSOR │ arguments to mon‐ │
69│ │ │ goc_collec‐ │
70│ │ │ tion_find_with_opts, │
71│ │ │ or you called mon‐ │
72│ │ │ goc_cursor_next on │
73│ │ │ a completed or │
74│ │ │ failed cursor, or │
75│ │ │ the cursor timed │
76│ │ │ out on the server. │
77├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
78│ │ MON‐ │ A resume token was │
79│ │ GOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN │ not returned in a │
80│ │ │ document found with │
81│ │ │ mon‐ │
82│ │ │ goc_change_stream_next │
83├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
84│MONGOC_ERROR_QUERY │ MONGOC_ERROR_QUERY_FAILURE │ Error API Version 1: │
85│ │ │ Server error from com‐ │
86│ │ │ mand or query. The │
87│ │ │ server error message │
88│ │ │ is in message. │
89├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
90│MONGOC_ERROR_SERVER │ MONGOC_ERROR_QUERY_FAILURE │ Error API Version 2: │
91│ │ │ Server error from com‐ │
92│ │ │ mand or query. The │
93│ │ │ server error message │
94│ │ │ is in message. │
95├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
96│MONGOC_ERROR_SASL │ A SASL error code. │ man sasl_errors for a │
97│ │ │ list of codes. │
98├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
99│MONGOC_ERROR_BSON │ MONGOC_ERROR_BSON_INVALID │ You passed an invalid │
100│ │ │ or oversized BSON doc‐ │
101│ │ │ ument as a parameter, │
102│ │ │ or called mongoc_col‐ │
103│ │ │ lection_create_index │
104│ │ │ with invalid keys, or │
105│ │ │ the server reply was │
106│ │ │ corrupt. │
107├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
108│MONGOC_ERROR_NAMES‐ │ MONGOC_ERROR_NAMESPACE_INVALID │ You tried to create a │
109│PACE │ │ collection with an │
110│ │ │ invalid name. │
111├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
112│MONGOC_ERROR_COM‐ │ MONGOC_ERROR_COMMAND_INVALID_ARG │ Many functions set │
113│MAND │ │ this error code when │
114│ │ │ passed bad parameters. │
115│ │ │ Print the error mes‐ │
116│ │ │ sage for details. │
117├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
118│ │ MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION │ You tried to use a │
119│ │ │ command option the │
120│ │ │ server does not sup‐ │
121│ │ │ port. │
122├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
123│ │ MONGOC_ERROR_DUPLICATE_KEY │ An insert or update │
124│ │ │ failed because because │
125│ │ │ of a duplicate _id or │
126│ │ │ other unique-index │
127│ │ │ violation. │
128└────────────────────────┴─────────────────────────────────────────┴───────────────────────────────────────┘
129│MONGOC_ERROR_COM‐ │ Error code from server. │ Error API Version 1: │
134│MAND │ │ Server error from a │
135│ │ │ command. The server │
136│ │ │ error message is in │
137│ │ │ message. │
138├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
139│MONGOC_ERROR_SERVER │ Error code from server. │ Error API Version 2: │
140│ │ │ Server error from a │
141│ │ │ command. The server │
142│ │ │ error message is in │
143│ │ │ message. │
144├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
145│MONGOC_ERROR_COL‐ │ MONGOC_ERROR_COLLECTION_INSERT_FAILED, │ Invalid or empty input │
146│LECTION │ MONGOC_ERROR_COLLECTION_UPDATE_FAILED, │ to mongoc_collec‐ │
147│ │ MONGOC_ERROR_COLLECTION_DELETE_FAILED. │ tion_insert_one, mon‐ │
148│ │ │ goc_collec‐ │
149│ │ │ tion_insert_bulk, mon‐ │
150│ │ │ goc_collec‐ │
151│ │ │ tion_update_one, mon‐ │
152│ │ │ goc_collec‐ │
153│ │ │ tion_update_many, mon‐ │
154│ │ │ goc_collec‐ │
155│ │ │ tion_replace_one, mon‐ │
156│ │ │ goc_collec‐ │
157│ │ │ tion_delete_one, or │
158│ │ │ mongoc_collec‐ │
159│ │ │ tion_delete_many. │
160├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
161│MONGOC_ERROR_COL‐ │ Error code from server. │ Error API Version 1: │
162│LECTION │ │ Server error from mon‐ │
163│ │ │ goc_collec‐ │
164│ │ │ tion_insert_one, mon‐ │
165│ │ │ goc_collec‐ │
166│ │ │ tion_insert_bulk, mon‐ │
167│ │ │ goc_collec‐ │
168│ │ │ tion_update_one, mon‐ │
169│ │ │ goc_collec‐ │
170│ │ │ tion_update_many, mon‐ │
171│ │ │ goc_collec‐ │
172│ │ │ tion_replace_one, mon‐ │
173│ │ │ goc_collec‐ │
174│ │ │ tion_delete_one, or │
175│ │ │ mongoc_collec‐ │
176│ │ │ tion_delete_many. │
177├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
178│MONGOC_ERROR_SERVER │ Error code from server. │ Error API Version 2: │
179│ │ │ Server error from mon‐ │
180│ │ │ goc_collec‐ │
181│ │ │ tion_insert_one, mon‐ │
182│ │ │ goc_collec‐ │
183│ │ │ tion_insert_bulk, mon‐ │
184│ │ │ goc_collec‐ │
185│ │ │ tion_update_one, mon‐ │
186│ │ │ goc_collec‐ │
187│ │ │ tion_update_many, mon‐ │
188│ │ │ goc_collec‐ │
189│ │ │ tion_replace_one, mon‐ │
190│ │ │ goc_collec‐ │
191│ │ │ tion_delete_one, or │
192│ │ │ mongoc_collec‐ │
193│ │ │ tion_delete_many. │
194└────────────────────────┴─────────────────────────────────────────┴───────────────────────────────────────┘
195│MONGOC_ERROR_GRIDFS │ MONGOC_ERROR_GRIDFS_CHUNK_MISSING │ The GridFS file is │
200│ │ │ missing a document in │
201│ │ │ its chunks collection. │
202├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
203│ │ MONGOC_ERROR_GRIDFS_CORRUPT │ A data inconsistency │
204│ │ │ was detected in │
205│ │ │ GridFS. │
206├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
207│ │ MONGOC_ERROR_GRIDFS_INVALID_FILENAME │ You passed a NULL │
208│ │ │ filename to mon‐ │
209│ │ │ goc_gridfs_remove_by_file‐ │
210│ │ │ name. │
211├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
212│ │ MONGOC_ERROR_GRIDFS_PROTOCOL_ERROR │ You called mon‐ │
213│ │ │ goc_gridfs_file_set_id │
214│ │ │ after mon‐ │
215│ │ │ goc_gridfs_file_save, or │
216│ │ │ tried to write on a closed │
217│ │ │ GridFS stream. │
218├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
219│ │ MON‐ │ A GridFS file is missing │
220│ │ GOC_ERROR_GRIDFS_BUCKET_FILE_NOT_FOUND │ from files collection. │
221├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
222│ │ MONGOC_ERROR_GRIDFS_BUCKET_STREAM │ An error occurred on a │
223│ │ │ stream created from a │
224│ │ │ GridFS operation like mon‐ │
225│ │ │ goc_gridfs_bucket_upload_from_stream. │
226├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
227│MONGOC_ERROR_SCRAM │ MONGOC_ERROR_SCRAM_PROTOCOL_ERROR │ Failure in SCRAM-SHA-1 authentica‐ │
228│ │ │ tion. │
229├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
230│MON‐ │ MONGOC_ERROR_SERVER_SELECTION_FAILURE │ No replica set member or mongos is │
231│GOC_ERROR_SERVER_SELEC‐ │ │ available, or none matches your read │
232│TION │ │ preference, or you supplied an │
233│ │ │ invalid mongoc_read_prefs_t. │
234├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
235│MONGOC_ERROR_WRITE_CON‐ │ Error code from server. │ There was a write concern error or │
236│CERN │ │ timeout from the server. │
237├────────────────────────┼─────────────────────────────────────────┼───────────────────────────────────────┤
238│MONGOC_ERROR_TRANSAC‐ │ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start a transaction │
239│TION │ │ when one is already in progress, or │
240│ │ │ commit or abort when there is no │
241│ │ │ transaction. │
242└────────────────────────┴─────────────────────────────────────────┴───────────────────────────────────────┘
243
245 In some cases your application must make decisions based on what cate‐
246 gory of error the driver has returned, but these categories do not cor‐
247 respond perfectly to an error domain or code. In such cases, error
248 labels provide a reliable way to determine how your application should
249 respond to an error.
250 Any C Driver function that has a bson_t out-parameter named reply may
252 include error labels to the reply, in the form of a BSON field named
253 "errorLabels" containing an array of strings:
254 { "errorLabels": [ "TransientTransactionError" ] }
256 Use mongoc_error_has_label to test if a reply contains a specific
258 label. See mongoc_client_session_start_transaction for example code
259 that demonstrates the use of error labels in application logic.
260 The following error labels are currently defined. Future versions of
262 MongoDB may introduce new labels.
263 TransientTransactionError
265 Within a multi-document transaction, certain errors can leave the
266 transaction in an unknown or aborted state. These include write con‐
267 flicts, primary stepdowns, and network errors. In response, the appli‐
268 cation should abort the transaction and try the same sequence of opera‐
269 tions again in a new transaction.
270 UnknownTransactionCommitResult
272 When mongoc_client_session_commit_transaction encounters a network
273 error or certain server errors, it is not known whether the transaction
274 was committed. Applications should attempt to commit the transaction
275 again until: the commit succeeds, the commit fails with an error not
276 labeled "UnknownTransactionCommitResult", or the application chooses to
277 give up.
278
280 The driver's error reporting began with a design flaw: when the error
281 domain is MONGOC_ERROR_COLLECTION, MONGOC_ERROR_QUERY, or MON‐
282 GOC_ERROR_COMMAND, the error code might originate from the server or
283 the driver. An application cannot always know where an error origi‐
284 nated, and therefore cannot tell what the code means.
285 For example, if mongoc_collection_update_one sets the error's domain to
287 MONGOC_ERROR_COLLECTION and its code to 24, the application cannot know
288 whether 24 is the generic driver error code MONGOC_ERROR_COLLEC‐
289 TION_UPDATE_FAILED or the specific server error code "LockTimeout".
290 To fix this flaw while preserving backward compatibility, the C Driver
292 1.4 introduces "Error API Versions". Version 1, the default Error API
293 Version, maintains the flawed behavior. Version 2 adds a new error
294 domain, MONGOC_ERROR_SERVER. In Version 2, error codes originating on
295 the server always have error domain MONGOC_ERROR_SERVER or MON‐
296 GOC_ERROR_WRITE_CONCERN. When the driver uses Version 2 the application
297 can always determine the origin and meaning of error codes. New appli‐
298 cations should use Version 2, and existing applications should be
299 updated to use Version 2 as well.
300 ┌──────────────────────┬──────────────────────┬──────────────────────┐
302 │Error Source │ API Version 1 │ API Version 2 │
303 ├──────────────────────┼──────────────────────┼──────────────────────┤
304 │mongoc_cursor_error │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
305 ├──────────────────────┼──────────────────────┼──────────────────────┤
306 │mongoc_client_com‐ │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
307 │mand_with_opts, │ │ │
308 │mongoc_data‐ │ │ │
309 │base_com‐ │ │ │
310 │mand_with_opts, and │ │ │
311 │other command func‐ │ │ │
312 │tions │ │ │
313 ├──────────────────────┼──────────────────────┼──────────────────────┤
314 │mongoc_collec‐ │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
315 │tion_count_with_opts │ │ │
316 │mon‐ │ │ │
317 │goc_client_get_data‐ │ │ │
318 │base_names_with_opts, │ │ │
319 │and other command │ │ │
320 │helper functions │ │ │
321 └──────────────────────┴──────────────────────┴──────────────────────┘
322 │mongoc_collec‐ │ MONGOC_ERROR_COM‐ │ MONGOC_ERROR_SERVER │
336 │tion_insert_one mon‐ │ MAND │ │
337 │goc_collec‐ │ │ │
338 │tion_insert_bulk mon‐ │ │ │
339 │goc_collec‐ │ │ │
340 │tion_update_one mon‐ │ │ │
341 │goc_collec‐ │ │ │
342 │tion_update_many mon‐ │ │ │
343 │goc_collec‐ │ │ │
344 │tion_replace_one mon‐ │ │ │
345 │goc_collec‐ │ │ │
346 │tion_delete_one mon‐ │ │ │
347 │goc_collec‐ │ │ │
348 │tion_delete_many │ │ │
349 ├──────────────────────┼──────────────────────┼──────────────────────┤
350 │mongoc_bulk_opera‐ │ MONGOC_ERROR_COM‐ │ MONGOC_ERROR_SERVER │
351 │tion_execute │ MAND │ │
352 ├──────────────────────┼──────────────────────┼──────────────────────┤
353 │Write-concern timeout │ MON‐ │ MON‐ │
354 │ │ GOC_ERROR_WRITE_CON‐ │ GOC_ERROR_WRITE_CON‐ │
355 │ │ CERN │ CERN │
356 └──────────────────────┴──────────────────────┴──────────────────────┘
357 The Error API Versions are defined with MONGOC_ERROR_API_VERSION_LEGACY
359 and MONGOC_ERROR_API_VERSION_2. Set the version with mon‐
360 goc_client_set_error_api or mongoc_client_pool_set_error_api.
361
363 MongoDB Server Error Codes
364
366 MongoDB, Inc
367
369 2017-present, MongoDB, Inc
3701.14.0 Feb 22, 2019 MONGOC_ERRORS(3)