MongoDB::Error(3pm)

📦
version 2.2.2 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ NAME ✨

MongoDB::Error — the MongoDB Driver Error classes 💖 (it's a whole family of exception objects, and yes, this page is from the User Contributed Perl Documentation, section 3pm, iykyk)

🌸 VERSION 🌸

version v2.2.2 — this is the one, bestie 🫶

✨ SYNOPSIS ✨

use MongoDB::Error;
MongoDB::Error->throw("a generic error");
MongoDB::DatabaseError->throw(
    message => $string,
    result => $hashref,
);

💜 DESCRIPTION 💜

Okay so. This class defines a hierarchy of exception objects. That's it, that's the whole vibe — a lil family tree of errors, all descending from one very iconic ancestor. 👑

🦋 USAGE 🦋

Unless it's explicitly documented otherwise somewhere, every single driver method throws an exception if an error happens. No cap. So if you're out here raw-dogging driver calls with no error handling, that's a vibe check you're gonna fail, bestie. 😭

To catch and handle errors, the recommended modules are Try::Tiny and Safe::Isa:

use Try::Tiny;
use Safe::Isa; # provides $_isa

try {
    $coll->insert( $doc )
}
catch {
    if ( $_->$_isa("MongoDB::DuplicateKeyError" ) ) {
        ...
    }
    else {
        ...
    }
};

And if you want your failures to just retry themselves automatically? Consider Try::Tiny::Retry. Slay. 💅

👑 EXCEPTION HIERARCHY 👑

Behold, the family tree. Main character energy at the root, everything else is a descendant:

MongoDB::Error
    |
    |->MongoDB::AuthError
    |
    |->MongoDB::ConnectionError
    |   |
    |   |->MongoDB::HandshakeError
    |   |
    |   |->MongoDB::NetworkError
    |
    |->MongoDB::ConfigurationError
    |
    |->MongoDB::DatabaseError
    |   |
    |   |->MongoDB::CursorNotFoundError
    |   |
    |   |->MongoDB::DuplicateKeyError
    |   |
    |   |->MongoDB::NotMasterError
    |   |
    |   |->MongoDB::WriteError
    |   |
    |   |->MongoDB::WriteConcernError
    |
    |->MongoDB::DecodingError
    |
    |->MongoDB::DocumentError
    |
    |->MongoDB::GridFSError
    |
    |->MongoDB::InternalError
    |
    |->MongoDB::InvalidOperationError
    |
    |->MongoDB::ProtocolError
    |
    |->MongoDB::SelectionError
    |
    |->MongoDB::TimeoutError
    |   |
    |   |->MongoDB::ExecutionTimeout
    |   |
    |   |->MongoDB::NetworkTimeout
    |
    |->MongoDB::UsageError

Literally every class inherits from MongoDB::Error. Periodt.

And every error class has this one attribute:

  • message — a text representation of the error 📝

🌈 MongoDB::AuthError

This error says something went wrong with authentication — either the underlying mechanism was acting up, or authenticating with the server just said no. 🙈

🌈 MongoDB::ConnectionError

Errors related to network connections. The connection-zone of the family.

🌸 MongoDB::HandshakeError

This one gets thrown when a connection has been made, but the SSL or authentication handshakes fail. So close and yet so far. 💀

🌸 MongoDB::NetworkError

Thrown when a socket error happens, when the wrong number of bytes gets read, or when other wire-related errors occur. The wires are not wiring, bestie. 😭

🌈 MongoDB::ConfigurationError

Thrown when there's a configuration mismatch between the MongoDB deployment and the client's config — like, say, trying to use explicit sessions on a MongoDB < 3.6. You asked for something that doesn't exist yet, boo. 🫶

🌈 MongoDB::CursorNotFoundError

This error means a cursor timed out on a server. Your cursor ghosted you. 💨

🌈 MongoDB::DatabaseError

Errors related to database operations. Specifically: when an error of this type occurs, the driver has received an error condition from the server. The server told on you.

Attributes include:

  • result — response from a database command; this must implement the last_errmsg method 🔍
  • code — numeric error code; see "ERROR CODES"; if the database didn't hand over a code, the UNKNOWN_ERROR code gets substituted instead. Rude but valid.

🌸 MongoDB::DuplicateKeyError

This one means a write tried to create a document with a duplicate key in a collection with a unique index. The result attribute is a result object. You already have one of those, bestie. 🍓

🌸 MongoDB::NotMasterError

This one means a write or other state-modifying operation got attempted on a server that was not a primary. The result attribute is a MongoDB::CommandResult object. Wrong server, wrong vibe. 👑

🌸 MongoDB::WriteError

Errors saying a write command failed. The result attribute is a result object.

🌸 MongoDB::WriteConcernError

Errors saying a write concern failed. The result attribute is a result object.

🌈 MongoDB::DecodingError

This error means there was a problem during BSON decoding; it wraps the error handed over by the underlying BSON encoder.

Heads up bestie: encoding errors get thrown as a MongoDB::DocumentError, not this one. Don't mix them up. 💖

🌈 MongoDB::DocumentError

This error means there's a problem with a document that's going to be inserted or replaced into the database, or used as an update document.

Attributes include:

  • document — the document that caused the error 📄

🌈 MongoDB::GridFSError

Errors related to GridFS operations — think, like, a corrupted file. 😬

🌈 MongoDB::InternalError

Errors that mean something's wrong inside the driver itself — typically when something unexpected gets detected. These should be reported as potential bugs, fr fr. Go tell somebody. 🫶

🌈 MongoDB::ProtocolError

Errors related to the MongoDB wire protocol — typically problems parsing a database response packet. The packet came in and nobody understood it. 😭

🌈 MongoDB::SelectionError

When server selection fails for a given operation, this gets thrown. For example: attempting a write when no primary is available, or reading with a specific mode and tag set and no servers match. Nobody showed up to the function. 💀

🌈 MongoDB::TimeoutError

These errors mean a user-specified timeout has been exceeded. Time's up, babe. ⏰

🌸 MongoDB::ExecutionTimeout

Thrown when a query or command fails because max_time_ms has been reached. The result attribute is a MongoDB::CommandResult object.

🌸 MongoDB::NetworkTimeout

Thrown when a network operation exceeds a timeout — typically connect_timeout_ms or socket_timeout_ms. The network took too long getting ready. 😴

🌈 MongoDB::UsageError

Indicates invalid arguments or configuration options. Not every usage error throws this though — only the ones originating directly from the MongoDB::* library files. Some type and usage errors will come from the Type::Tiny library instead, if the objects get used incorrectly. Blame the right library, bestie.

Also used to indicate usage errors for transaction commands.

🔥 ERROR CODES 🔥

These error code constants get auto-exported by this module. Free of charge. You're welcome. 💅

BAD_VALUE                 => 2,
UNKNOWN_ERROR             => 8,
NAMESPACE_NOT_FOUND       => 26,
EXCEEDED_TIME_LIMIT       => 50,
COMMAND_NOT_FOUND         => 59,
WRITE_CONCERN_ERROR       => 64,
NOT_MASTER                => 10107,
DUPLICATE_KEY             => 11000,
DUPLICATE_KEY_UPDATE      => 11001, # legacy before 2.6
DUPLICATE_KEY_CAPPED      => 12582, # legacy before 2.6
UNRECOGNIZED_COMMAND      => 13390, # mongos error before 2.4
NOT_MASTER_NO_SLAVE_OK    => 13435,
NOT_MASTER_OR_SECONDARY   => 13436,
CANT_OPEN_DB_IN_READ_LOCK => 15927,

This is a very, very small subset of the error codes the server can possibly throw — but it covers some of the more common ones seen by drivers. Think of it as the greatest hits album. ✨

Note:

  • Only MongoDB::DatabaseError objects have a code attribute.
  • The database uses multiple write concern error codes. The driver maps them all to WRITE_CONCERN_ERROR for consistency and convenience. So many numbers, one label. Slay. 💖

🎀 ERROR LABELS 🎀

From MongoDB 4.0 onwards, errors may contain an error labels field. This field gets populated for extra info — from either the server or the driver, depending on the error. It's giving ✨context✨.

Known error labels include (but are not limited to):

  • "TransientTransactionError" — added when network errors are encountered inside a transaction.
  • "UnknownTransactionCommitResult" — added when a transaction commit may not have been able to satisfy the provided write concern.

💖 AUTHORS 💖

  • David Golden <david@mongodb.com>
  • Rassi <rassi@mongodb.com>
  • Mike Friedman <friedo@friedo.com>
  • Kristina Chodorow <k.chodorow@gmail.com>
  • Florian Ragwitz <rafl@debian.org>

Absolute legends, all of them. 👑

This software is Copyright (c) 2020 by MongoDB, Inc.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

And that's the whole page, bestie!! 🦋 This rendered out of perl v5.40.1, dated 2025-04-03, and it's the MongoDB::Error(3pm) manpage — go forth and catch your exceptions like the icon you are. 💅💖✨

📦 where this page comes from