=================================
Error Handling in MongoDB Drivers
=================================

.. default-domain:: mongodb

.. include:: /includes/note-legacy.rst

If an error occurs on a query or on a ``getMore`` operation sent by a
:term:`replica set` member, MongoDB returns an error object instead of
user data.

The error object's first field has the reserved key ``$err``. For example:

.. code-block:: sh

   { $err : "some error message" }

The ``$err`` value can be of any type but is usually a string.

Drivers typically check for this return code explicitly and take action
rather than return the object to the user. The query results flags
include a set bit when ``$err`` is returned.

.. code-block:: sh

   /* db response format

   Query or GetMore: // see struct QueryResult
     int resultFlags;
     int64 cursorID;
     int startingFrom;
     int nReturned;
     list of marshalled JSObjects;

   */

   struct QueryResult : public MsgData {
     enum {
       ResultFlag_CursorNotFound = 1, /* returned, with zero results, when getMore is called but the cursor id is not valid at the server. */
       ResultFlag_ErrSet = 2          /* { $err : ... } is being returned */
     };
     ...
   };

.. seealso::

   - The :wiki:`Driver and Integration Center
     <Writing+Drivers+and+Tools>` for information about the latest
     drivers

   - The main :wiki:`Database Internals page <Database+Internals>`