1MONGOC_ERRORS(3) libmongoc MONGOC_ERRORS(3)
2
6 mongoc_errors - Error Reporting « libmongoc
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│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 │
43│ │ │ mongoc_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 │ In-Use Encryption. │
53├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
54│ │ MONGOC_ER‐ │ Failure related to │
55│ │ ROR_CLIENT_IN‐ │ In-Use Encryption. │
56│ │ VALID_ENCRYP‐ │ │
57│ │ TION_STATE │ │
58└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
59│ │ 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 │
96│ │ │ mongoc_collection_find_with_opts(), │
97│ │ │ or you called │
98│ │ │ mongoc_cursor_next() │
99│ │ │ on a completed or │
100│ │ │ failed cursor, or │
101│ │ │ the cursor timed │
102│ │ │ out on the server. │
103├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
104│ │ MONGOC_ER‐ │ A resume token was not returned in │
105│ │ ROR_CHANGE_STREAM_NO_RE‐ │ a document found with │
106│ │ SUME_TOKEN │ mongoc_change_stream_next() │
107├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
108│MONGOC_ERROR_QUERY │ MONGOC_ERROR_QUERY_FAIL‐ │ Error API Version 1: Server error │
109│ │ URE │ from command or query. The server │
110│ │ │ error message is in message. │
111├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
112│MONGOC_ERROR_SERVER │ MONGOC_ERROR_QUERY_FAIL‐ │ Error API Version 2: Server error │
113│ │ URE │ from command or query. The server │
114│ │ │ error message is in message. │
115├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
116│MONGOC_ERROR_SASL │ A SASL error code. │ man sasl_errors for a list of │
117│ │ │ codes. │
118├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
119│MONGOC_ERROR_BSON │ MONGOC_ERROR_BSON_IN‐ │ You passed an invalid or oversized │
120│ │ VALID │ BSON document as a parameter, or │
121│ │ │ called │
122│ │ │ mongoc_collection_create_index() │
123│ │ │ with invalid keys, or the server │
124│ │ │ reply was corrupt. │
125├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
126│MONGOC_ERROR_NAME‐ │ MONGOC_ERROR_NAME‐ │ You tried to create a collection │
127│SPACE │ SPACE_INVALID │ with an invalid name. │
128└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
129│MONGOC_ERROR_COM‐ │ MONGOC_ERROR_COMMAND_IN‐ │ Many functions set this error code │
134│MAND │ VALID_ARG │ when passed bad parameters. Print │
135│ │ │ the error message for details. │
136├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
137│ │ MONGOC_ERROR_PROTO‐ │ You tried to use a command option │
138│ │ COL_BAD_WIRE_VERSION │ the server does not support. │
139├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
140│ │ MONGOC_ERROR_DUPLI‐ │ An insert or update failed because │
141│ │ CATE_KEY │ because of a duplicate _id or other │
142│ │ │ unique-index violation. │
143├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
144│ │ MONGOC_ER‐ │ The operation failed because max‐ │
145│ │ ROR_MAX_TIME_MS_EXPIRED │ TimeMS expired. │
146├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
147│ │ MONGOC_ERROR_SERVER_SE‐ │ The serverId option for an opera‐ │
148│ │ LECTION_INVALID_ID │ tion conflicts with the pinned │
149│ │ │ server for that operation's client │
150│ │ │ session (denoted by the sessionId │
151│ │ │ option). │
152├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
153│MONGOC_ERROR_COM‐ │ Error code from server. │ Error API Version 1: Server error │
154│MAND │ │ from a command. The server error │
155│ │ │ message is in message. │
156├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
157│MONGOC_ERROR_SERVER │ Error code from server. │ Error API Version 2: Server error │
158│ │ │ from a command. The server error │
159│ │ │ message is in message. │
160├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
161│MONGOC_ERROR_COL‐ │ MONGOC_ERROR_COLLEC‐ │ Invalid or empty input to │
162│LECTION │ TION_INSERT_FAILED, MON‐ │ mongoc_collection_insert_one(), │
163│ │ GOC_ERROR_COLLECTION_UP‐ │ mongoc_collection_insert_bulk(), │
164│ │ DATE_FAILED, MONGOC_ER‐ │ mongoc_collection_update_one(), │
165│ │ ROR_COLLEC‐ │ mongoc_collection_update_many(), │
166│ │ TION_DELETE_FAILED. │ mongoc_collection_replace_one(), │
167│ │ │ mongoc_collection_delete_one(), or │
168│ │ │ mongoc_collection_delete_many(). │
169├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
170│MONGOC_ERROR_COL‐ │ Error code from server. │ Error API Version 1: Server error │
171│LECTION │ │ from │
172│ │ │ mongoc_collection_insert_one(), │
173│ │ │ mongoc_collection_insert_bulk(), │
174│ │ │ mongoc_collection_update_one(), │
175│ │ │ mongoc_collection_update_many(), │
176│ │ │ mongoc_collection_replace_one(), │
177├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
178│MONGOC_ERROR_SERVER │ Error code from server. │ Error API Version 2: Server error │
179│ │ │ from │
180│ │ │ mongoc_collection_insert_one(), │
181│ │ │ mongoc_collection_insert_bulk(), │
182│ │ │ mongoc_collection_update_one(), │
183│ │ │ mongoc_collection_update_many(), │
184│ │ │ mongoc_collection_replace_one(), │
185├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
186│MONGOC_ERROR_GRIDFS │ MONGOC_ER‐ │ The GridFS file is missing a docu‐ │
187│ │ ROR_GRIDFS_CHUNK_MISSING │ ment in its chunks collection. │
188├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
189│ │ MONGOC_ERROR_GRIDFS_COR‐ │ A data inconsistency was detected │
190│ │ RUPT │ in GridFS. │
191├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
192│ │ MONGOC_ERROR_GRIDFS_IN‐ │ You passed a NULL filename to │
193│ │ VALID_FILENAME │ mongoc_gridfs_remove_by_filename(). │
194└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
195│ │ MONGOC_ERROR_GRIDFS_PRO‐ │ You called │
200│ │ TOCOL_ERROR │ mongoc_gridfs_file_set_id() after │
201│ │ │ mongoc_gridfs_file_save(), or tried │
202│ │ │ to write on a closed GridFS stream. │
203├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
204│ │ MONGOC_ER‐ │ A GridFS file is missing from files │
205│ │ ROR_GRIDFS_BUCKET_FILE_NOT_FOUND │ collection. │
206├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
207│ │ MONGOC_ER‐ │ An error occurred on a stream cre‐ │
208│ │ ROR_GRIDFS_BUCKET_STREAM │ ated from a GridFS operation like │
209│ │ │ mongoc_gridfs_bucket_upload_from_stream(). │
210├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
211│MONGOC_ERROR_SCRAM │ MONGOC_ERROR_SCRAM_PROTOCOL_ER‐ │ Failure in SCRAM-SHA-1 authentication. │
212│ │ ROR │ │
213├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
214│MONGOC_ER‐ │ MONGOC_ERROR_SERVER_SELEC‐ │ No replica set member or mongos is avail‐ │
215│ROR_SERVER_SELEC‐ │ TION_FAILURE │ able, or none matches your read prefer‐ │
216│TION │ │ ence, or you supplied an invalid │
217│ │ │ mongoc_read_prefs_t. │
218├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
219│MONGOC_ER‐ │ Error code from server. │ There was a write concern error or timeout │
220│ROR_WRITE_CONCERN │ │ from the server. │
221├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
222│MONGOC_ERROR_TRANS‐ │ MONGOC_ERROR_TRANSACTION_INVALID │ You attempted to start a transaction when │
223│ACTION │ │ one is already in progress, or commit or │
224│ │ │ abort when there is no transaction. │
225├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
226│MONGOC_ER‐ │ Error code produced by libmon‐ │ An error occurred in the library responsi‐ │
227│ROR_CLIENT_SIDE_EN‐ │ gocrypt. │ ble for In-Use Encryption │
228│CRYPTION │ │ │
229├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
230│MONGOC_ERROR_AZURE │ MONGOC_ERROR_KMS_SERVER_HTTP │ An Azure HTTP service responded with an │
231│ │ │ error status │
232├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
233│ │ MONGOC_ERROR_KMS_SERVER_BAD_JSON │ An Azure service responded with invalid │
234│ │ │ JSON data │
235├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
236│MONGOC_ERROR_GCP │ MONGOC_ERROR_KMS_SERVER_HTTP │ A GCP HTTP service responded with an error │
237│ │ │ status │
238├────────────────────┼──────────────────────────────────┼────────────────────────────────────────────┤
239│ │ MONGOC_ERROR_KMS_SERVER_BAD_JSON │ A GCP service responded with invalid JSON │
240│ │ │ data │
241└────────────────────┴──────────────────────────────────┴────────────────────────────────────────────┘
242
244 In some cases your application must make decisions based on what cate‐
245 gory of error the driver has returned, but these categories do not cor‐
246 respond perfectly to an error domain or code. In such cases, error la‐
247 bels provide a reliable way to determine how your application should
248 respond to an error.
249 Any C Driver function that has a bson_t out-parameter named reply may
251 include error labels to the reply, in the form of a BSON field named
252 "errorLabels" containing an array of strings:
253 { "errorLabels": [ "TransientTransactionError" ] }
255 Use mongoc_error_has_label() to test if a reply contains a specific la‐
257 bel. See mongoc_client_session_start_transaction() for example code
258 that demonstrates the use of error labels in application logic.
259 The following error labels are currently defined. Future versions of
261 MongoDB may introduce new labels.
262 TransientTransactionError
264 Within a multi-document transaction, certain errors can leave the
265 transaction in an unknown or aborted state. These include write con‐
266 flicts, primary stepdowns, and network errors. In response, the appli‐
267 cation should abort the transaction and try the same sequence of opera‐
268 tions again in a new transaction.
269 UnknownTransactionCommitResult
271 When mongoc_client_session_commit_transaction() encounters a network
272 error or certain server errors, it is not known whether the transaction
273 was committed. Applications should attempt to commit the transaction
274 again until: the commit succeeds, the commit fails with an error not
275 labeled "UnknownTransactionCommitResult", or the application chooses to
276 give up.
277
279 The driver's error reporting began with a design flaw: when the error
280 domain is MONGOC_ERROR_COLLECTION, MONGOC_ERROR_QUERY, or MONGOC_ER‐
281 ROR_COMMAND, the error code might originate from the server or the
282 driver. An application cannot always know where an error originated,
283 and therefore cannot tell what the code means.
284 For example, if mongoc_collection_update_one() sets the error's domain
286 to MONGOC_ERROR_COLLECTION and its code to 24, the application cannot
287 know whether 24 is the generic driver error code MONGOC_ERROR_COLLEC‐
288 TION_UPDATE_FAILED or the specific server error code "LockTimeout".
289 To fix this flaw while preserving backward compatibility, the C Driver
291 1.4 introduces "Error API Versions". Version 1, the default Error API
292 Version, maintains the flawed behavior. Version 2 adds a new error do‐
293 main, MONGOC_ERROR_SERVER. In Version 2, error codes originating on the
294 server always have error domain MONGOC_ERROR_SERVER or MONGOC_ER‐
295 ROR_WRITE_CONCERN. When the driver uses Version 2 the application can
296 always determine the origin and meaning of error codes. New applica‐
297 tions should use Version 2, and existing applications should be updated
298 to use Version 2 as well.
299┌──────────────────────────────────────────────┬────────────────────┬─────────────────────┐
301│Error Source │ API Version 1 │ API Version 2 │
302├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
303│mongoc_cursor_error() │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
304├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
305│mongoc_client_command_with_opts(), │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
306│mongoc_database_command_with_opts(), │ │ │
307│and other command │ │ │
308│functions │ │ │
309├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
310│mongoc_collection_count_with_opts() │ MONGOC_ERROR_QUERY │ MONGOC_ERROR_SERVER │
311│mongoc_client_get_database_names_with_opts(), │ │ │
312│and other command helper functions │ │ │
313├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
314│mongoc_collection_insert_one() │ MONGOC_ERROR_COM‐ │ MONGOC_ERROR_SERVER │
315│mongoc_collection_insert_bulk() │ MAND │ │
316│mongoc_collection_update_one() │ │ │
317│mongoc_collection_update_many() │ │ │
318│mongoc_collection_replace_one() │ │ │
319│mongoc_collection_delete_one() │ │ │
320│mongoc_collection_delete_many() │ │ │
321├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
322│mongoc_bulk_operation_execute() │ MONGOC_ERROR_COM‐ │ MONGOC_ERROR_SERVER │
323│ │ MAND │ │
324├──────────────────────────────────────────────┼────────────────────┼─────────────────────┤
325│Write-concern timeout │ MONGOC_ER‐ │ MONGOC_ER‐ │
326│ │ ROR_WRITE_CONCERN │ ROR_WRITE_CONCERN │
327└──────────────────────────────────────────────┴────────────────────┴─────────────────────┘
328 The Error API Versions are defined with MONGOC_ERROR_API_VERSION_LEGACY
330 and MONGOC_ERROR_API_VERSION_2. Set the version with
331 mongoc_client_set_error_api() or mongoc_client_pool_set_error_api().
332 SEE ALSO:
334 MongoDB Server Error Codes
335
338 MongoDB, Inc
339
341 2017-present, MongoDB, Inc
3421.24.3 Aug 17, 2023 MONGOC_ERRORS(3)