errors – Exceptions raised by the pymongo package

Exceptions raised by PyMongo.

exception pymongo.errors.AutoReconnect(message='', errors=None)

Raised when a connection to the database is lost and an attempt to auto-reconnect will be made.

In order to auto-reconnect you must handle this exception, recognizing that the operation which caused it has not necessarily succeeded. Future operations will attempt to open a new connection to the database (and will continue to raise this exception until the first successful connection is made).

Subclass of ConnectionFailure.

Parameters:
Return type:

None

exception pymongo.errors.BulkWriteError(results)

Exception class for bulk write errors.

Added in version 2.7.

Parameters:

results (_DocumentOut)

Return type:

None

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.CollectionInvalid(message='', error_labels=None)

Raised when collection validation fails.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.ConfigurationError(message='', error_labels=None)

Raised when something is incorrectly configured.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.ConnectionFailure(message='', error_labels=None)

Raised when a connection to the database cannot be made or is lost.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.CursorNotFound(error, code=None, details=None, max_wire_version=None)

Raised while iterating query results if the cursor is invalidated on the server.

Added in version 2.7.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None

exception pymongo.errors.DocumentTooLarge

Raised when an encoded document is too large for the connected server.

exception pymongo.errors.DuplicateKeyError(error, code=None, details=None, max_wire_version=None)

Raised when an insert or update fails due to a duplicate key error.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None

exception pymongo.errors.EncryptedCollectionError(cause, encrypted_fields)

Raised when creating a collection with encrypted_fields fails.

Added in version 4.4.

Parameters:
Return type:

None

property encrypted_fields: Mapping[str, Any]

The encrypted_fields document that allows inferring which data keys are known to be created.

Note that the returned document is not guaranteed to contain information about all of the data keys that were created, for example in the case of an indefinite error like a timeout. Use the cause property to determine whether a definite or indefinite error caused this error, and only rely on the accuracy of the encrypted_fields if the error is definite.

exception pymongo.errors.EncryptionError(cause)

Raised when encryption or decryption fails.

This error always wraps another exception which can be retrieved via the cause property.

Added in version 3.9.

Parameters:

cause (Exception)

Return type:

None

property cause: Exception

The exception that caused this encryption or decryption error.

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.ExecutionTimeout(error, code=None, details=None, max_wire_version=None)

Raised when a database operation times out, exceeding the $maxTimeMS set in the query or command option.

Note

Requires server version >= 2.6.0

Added in version 2.7.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.InvalidName(message='', error_labels=None)

Raised when an invalid name is used.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.InvalidOperation(message='', error_labels=None)

Raised when a client attempts to perform an invalid operation.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.InvalidURI(message='', error_labels=None)

Raised when trying to parse an invalid mongodb URI.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.NetworkTimeout(message='', errors=None)

An operation on an open connection exceeded socketTimeoutMS.

The remaining connections in the pool stay open. In the case of a write operation, you cannot know whether it succeeded or failed.

Subclass of AutoReconnect.

Parameters:
Return type:

None

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.NotPrimaryError(message='', errors=None)

The server responded “not primary” or “node is recovering”.

These errors result from a query, write, or command. The operation failed because the client thought it was using the primary but the primary has stepped down, or the client thought it was using a healthy secondary but the secondary is stale and trying to recover.

The client launches a refresh operation on a background thread, to update its view of the server as soon as possible after throwing this exception.

Subclass of AutoReconnect.

Added in version 3.12.

Parameters:
Return type:

None

exception pymongo.errors.OperationFailure(error, code=None, details=None, max_wire_version=None)

Raised when a database operation fails.

Added in version 2.7: The details attribute.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None

property code: int | None

The error code returned by the server, if any.

property details: Mapping[str, Any] | None

The complete error document returned by the server.

Depending on the error that occurred, the error document may include useful information beyond just the error message. When connected to a mongos the error document may contain one or more subdocuments if errors occurred on multiple shards.

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.ProtocolError(message='', error_labels=None)

Raised for failures related to the wire protocol.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

exception pymongo.errors.PyMongoError(message='', error_labels=None)

Base class for all PyMongo exceptions.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

has_error_label(label)

Return True if this error contains the given label.

Added in version 3.7.

Parameters:

label (str)

Return type:

bool

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.ServerSelectionTimeoutError(message='', errors=None)

Thrown when no MongoDB server is available for an operation

If there is no suitable server for an operation PyMongo tries for serverSelectionTimeoutMS (default 30 seconds) to find one, then throws this exception. For example, it is thrown after attempting an operation when PyMongo cannot connect to any server, or if you attempt an insert into a replica set that has no primary and does not elect one within the timeout window, or if you attempt to query with a Read Preference that the replica set cannot satisfy.

Parameters:
Return type:

None

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.WTimeoutError(error, code=None, details=None, max_wire_version=None)

Raised when a database operation times out (i.e. wtimeout expires) before replication completes.

With newer versions of MongoDB the details attribute may include write concern fields like ‘n’, ‘updatedExisting’, or ‘writtenTo’.

Added in version 2.7.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.WaitQueueTimeoutError(message='', error_labels=None)

Raised when an operation times out waiting to checkout a connection from the pool.

Subclass of ConnectionFailure.

Added in version 4.2.

Parameters:

  • message (str)

  • error_labels (Optional[Iterable[str]])

Return type:

None

property timeout: bool

True if this error was caused by a timeout.

Added in version 4.2.

exception pymongo.errors.WriteConcernError(error, code=None, details=None, max_wire_version=None)

Base exception type for errors raised due to write concern.

Added in version 3.0.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None

exception pymongo.errors.WriteError(error, code=None, details=None, max_wire_version=None)

Base exception type for errors raised during write operations.

Added in version 3.0.

Parameters:

  • error (str)

  • code (Optional[int])

  • details (Optional[Mapping[str, Any]])

  • max_wire_version (Optional[int])

Return type:

None