Title: Error Class Hierarchy
Authors: Warren James, Andy Mina
Advisory Group: Daria Purdue, Eric Adum, Neal Beeken
All errors are derived from the MongoError
class which should never be instantiated.
There are five main error classes which stem from MongoError
: MongoDriverError
,
MongoNetworkError
, MongoServerError
, MongoCryptError
and MongoSystemError
.
The base class from which all errors in the Node driver subclass.
MongoError
should never be be directly instantiated.
graph TD
MongoError:::node --- MongoDriverError
MongoError:::node --- MongoNetworkError
MongoError:::node --- MongoServerError
MongoError:::node --- MongoSystemError
MongoError:::node --- MongoCryptError
MongoDriverError:::node --- MongoAPIError
MongoDriverError:::node --- MongoRuntimeError
linkStyle 0,1,2,3,4,5,6 stroke:#116149
classDef node fill:#13aa52,stroke:#21313c,color:#FAFBFC
Children of MongoError
include:
This class represents errors which originate in the driver itself or when the user incorrectly uses the driver. This class should never be directly instantiated.
Its children are the main classes of errors that most users will interact with: MongoAPIError
and MongoRuntimeError
.
This class represents errors which originate from misuse of the driver API and will generally be thrown before making contact with the server. This class should never be directly instantiated.
Children of MongoAPIError
Error Name | Description |
---|---|
MongoInvalidArgumentError | Thrown when the user supplies malformed or unexpected arguments or failed to provide a required argument or field. |
MongoCompatibilityError | Thrown when a feature that is not enabled or allowed for the current server configuration is used. |
MongoMissingCredentialsError | Thrown when a user fails to provide authentication credentials before attempting to connect. |
MongoMissingDependencyError | Thrown when a required module or dependency is not present. |
MongoExpiredSessionError | Thrown when the user attempts to operate on a session that is expired or closed. |
MongoTransactionError | Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). |
MongoTailableCursorError | Thrown when the user calls a function or method that is not supported on a tailable cursor. |
MongoCursorExhaustedError | Thrown when an attempt is made to read from a cursor that is exhausted. |
MongoCursorInUseError | Thrown when the user attempts to add options to an already initialized cursor. |
MongoServerClosedError | Thrown when an attempt is made to operate on a closed server. |
MongoTopologyClosedError | Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database. |
MongoNotConnectedError | Thrown when the user attempts to perform operations on a client that has not yet connected. |
MongoBatchReExecutionError | Thrown when a user attempts to re-execute a batch command when one of the constituent commands has failed. |
MongoConnectionStringError | Thrown when a user supplies an incorrect URI to the driver. |
MongoConnectionPoolClosedError | Thrown when a user attempts to operate on a connection pool that is expired or closed. |
This class represents errors which occur when the driver encounters unexpected input or reaches an unexpected/invalid internal state. This class should never be directly instantiated.
Children of MongoRuntimeError
Error Name | Description |
---|---|
MongoDecompressionError | Thrown when the driver fails to decompress data received from the server. |
MongoChangeStreamError | Thrown when an error is encountered when operating on a ChangeStream. |
MongoGridFSStreamError | Thrown when an unexpected state is reached when operating on a GridFS Stream. |
MongoGridFSChunkError | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream. |
MongoUnexpectedServerResponseError | Thrown when the driver receives a parsable response it did not expect from the server. |
Intended for the scenario where the MongoDB returns an unexpected response in relation to some state the driver is in. This error should NOT represent a response that couldn't be parsed due to errors in protocol formatting.
Ex. Server selection results in a feature detection change: this is not usually an unexpected response, but if while retrying an operation serverSelection returns a server with a lower wireVersion than expected, we can no longer proceed with the retry, so the response is unexpected in that case.
These are errors which prevent the driver from connecting to a mongo server instance. Children of this class include:
-
- Thrown when a timeout expires while attempting to connect to the mongo server
These are errors which wrap error responses received from the server.
These are errors which originate from faulty environment setup.
-
- Thrown when the driver fails to select a server to complete an operation
These are errors thrown from the driver's client side encryption logic.
-
- Thrown when an invalid argument has been provided to an encryption API
-
- Thrown when the driver fails to create data keys for an encrypted collection
-
- Thrown when the driver fails to create an encrypted collection
-
- Thrown when the driver encounters an error when fetching Azure KMS credentials
-
- Thrown when the HTTP request to the IDMS server times out when fetching Azure KMS credentials
The test plan consists of a series of prose tests. As numerous errors are being introduced, select classes will be tested. The classes to be tested will be selected based on three characteristics:
- The frequency with which users may encounter this error. Errors that users will likely run into, including but not limited to
MongoInvalidArgumentError
andMongoNetworkTimeoutError
, are a part of the test plan. Note: Error classes that should never be instantiated, such asMongoAPIError
andMongoRuntimeError
, will not be tested as the user should not encounter them. - The scope of the error. Errors that tackle a large subset of issues, including but not limited to
MongoServerError
andMongoSystemError
, will not be a part of the test plan. - The existing coverage of the error. Errors that are already covered in existing tests will not be a part of the test plan to avoid redundancy.
- Create a
MongoClient
object and supply a number in place of the connection string when calling.connect()
- Assert that
MongoInvalidArgumentError
is thrown.
- Assert that
- Fail to provide credentials when authenticating with the x509 mechanism.
- Assert that
MongoMissingCredentialsError
is thrown.
- Assert that
- Attempt to access a database without establishing a connection to a MongoDB server.
- Assert that
MongoNotConnectedError
is thrown.
- Assert that
- Attempt to execute
createCollection()
against a database that has been closed.- Assert that
MongoTopologyClosedError
is thrown.
- Assert that
- Attempt to continue reading a cursor after it has reached the end of the batch.
- Assert that
MongoCursorExhaustedError
is thrown.
- Assert that
- Attempt to execute a query against a server that has closed.
- Assert that
MongoServerClosedError
is thrown.
- Assert that
- Create a
MongoClient
object and set theconnectTimeoutMS
option to 1.- Assert that a
MongoNetworkTimeoutError
is thrown.
- Assert that a