MONGOC_CURSOR_ERROR_DOCUMENT(3)

💅 MONGOC_CURSOR_ERROR_DOCUMENT(3) 💅

okay bestie so this is a page from libmongoc (the MongoDB C driver, yes that one) and it's literally about finding out whether your cursor ✨ had a moment ✨ — like, did something go wrong while you were iterating? we're gonna find out together, no cap.

---

🌸 SYNOPSIS 🌸

bool
mongoc_cursor_error_document (mongoc_cursor_t *cursor,
                              bson_error_t *error,
                              const bson_t **reply);

---

🎀 PARAMETERS 🎀

• cursor — a mongoc_cursor_t. your little cursor guy. the main character of this whole situation.
• error — an optional location for a bson_error_t, or NULL if you're feeling lowkey hands-off about it.
• reply — a location for a bson_t. this is where the tea gets spilled.

---

🦋 DESCRIPTION 🦋

so this function checks to see if an error has occurred while iterating the cursor. a whole vibe check, basically.

if an error occurred client-side — for example if there was a network error or timeout, or the cursor was created with invalid parameters — then reply is set to an empty BSON document. it's giving "no thoughts, head empty" 🫶.

if an error occurred server-side, reply is set to the server's reply document with information about the error. the server literally sent receipts. obsessed.

---

💀 ERRORS 💀

errors are propagated via the error and reply parameters. that's it, that's the whole section. slay 💅

---

🔥 RETURNS 🔥

• False if no error has occurred. good for you, bestie.
• otherwise True, and error is set. not so good for you, bestie 😭

and if the function returns true and reply is not NULL, then reply is set to a pointer to a BSON document, which is either empty or the server's error response. important: the document is invalid after the cursor is freed with mongoc_cursor_destroy(). do not go chasing that pointer after the cursor is gone, it will not end well 🙈.

---

🌈 EXAMPLE 🌈

this example shows the difference between a client-side and server-side error. if the client cannot connect to the server, for example, the error message includes "No suitable servers found" and reply is set to an empty BSON document.

on the other hand, if the client connects to the server successfully and attempts to execute an invalid query, the error message comes from the server and reply is set to the server's reply document, with fields errmsg and code. iconic behavior honestly.

void
run_query (const char *uri_str, const bson_t *query)
{
   mongoc_client_t *client;
   mongoc_collection_t *collection;
   mongoc_cursor_t *cursor;
   const bson_t *doc;
   bson_error_t error;
   const bson_t *reply;
   char *str;

   client = mongoc_client_new (uri_str);

   mongoc_client_set_error_api (client, 2);

   collection = mongoc_client_get_collection (client, "db", "collection");
   cursor = mongoc_collection_find_with_opts (
      collection,
      query,
      NULL,  /* additional options */
      NULL); /* read prefs, NULL for default */

   /* this loop is never run: mongoc_cursor_next immediately returns false */
   while (mongoc_cursor_next (cursor, &doc)) {
   }

   if (mongoc_cursor_error_document (cursor, &error, &reply)) {
      str = bson_as_relaxed_extended_json (reply, NULL);
      fprintf (stderr, "Cursor Failure: %s\nReply: %s\n", error.message, str);
      bson_free (str);
   }

   mongoc_cursor_destroy (cursor);
   mongoc_collection_destroy (collection);
   mongoc_client_destroy (client);
}

int
main (int argc, char *argv[])
{
   bson_t *good_query;
   bson_t *bad_query;

   mongoc_init ();

   /* find documents matching the query {"x": 1} */
   good_query = BCON_NEW ("x", BCON_INT64 (1));

   /* Cause a network error. This will print an error and empty reply document:
    *
    * Cursor Failure: No suitable servers found (`serverSelectionTryOnce` set):
    *     [Failed to resolve 'fake-domain']
    *
    * Reply: { }
    *
    */
   run_query ("mongodb://fake-domain/?appname=cursor-example", good_query);

   /* invalid: {"x": {"$badOperator": 1}} */
   bad_query = BCON_NEW ("x", "{", "$badOperator", BCON_INT64 (1), "}");

   /* Cause a server error. This will print an error and server reply document:
    *
    * Cursor Failure: unknown operator: $badOperator
    *
    * Reply:
    * {"ok": 0.0,
    *  "errmsg":"unknown operator: $badOperator",
    *  "code": 2,
    *  "codeName":"BadValue"
    * }
    *
    */
   run_query ("mongodb://localhost/?appname=cursor-example", bad_query);

   bson_destroy (good_query);
   bson_destroy (bad_query);

   mongoc_cleanup ();

   return 0;
}

---

👑 AUTHOR 👑

MongoDB, Inc — the literal icons who wrote this.

💖 COPYRIGHT 💖

2009-present, MongoDB, Inc.

---

and that's the page, bestie!! 🧚✨ this lil writeup is from libmongoc version 2.5.6, dated Oct 09, 2026 — go forth and check your cursor errors responsibly 🍓💜