Scroll to navigation

MongoDB::Error(3pm) User Contributed Perl Documentation MongoDB::Error(3pm)

NAME

MongoDB::Error - MongoDB Driver Error classes

VERSION

version v1.4.5

SYNOPSIS

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

DESCRIPTION

This class defines a hierarchy of exception objects.

USAGE

Unless otherwise explicitly documented, all driver methods throw exceptions if an error occurs.

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

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

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

To retry failures automatically, consider using Try::Tiny::Retry.

EXCEPTION HIERARCHY

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

All classes inherit from "MongoDB::Error".

All error classes have the attribute:

•
message — a text representation of the error

MongoDB::AuthError

This error indicates a problem with authentication, either in the underlying mechanism or a problem authenticating with the server.

MongoDB::ConnectionError

Errors related to network connections.

MongoDB::HandshakeError

This error is thrown when a connection has been made, but SSL or authentication handshakes fail.

MongoDB::NetworkError

This error is thrown when a socket error occurs, when the wrong number of bytes are read, or other wire-related errors occur.

MongoDB::CursorNotFoundError

This error indicates that a cursor timed out on a server.

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.

Attributes include:

  • result — response from a database command; this must impliement the "last_errmsg" method
  • code — numeric error code; see "ERROR CODES"; if no code was provided by the database, the "UNKNOWN_ERROR" code will be substituted instead

MongoDB::DuplicateKeyError

This error indicates that a write attempted to create a document with a duplicate key in a collection with a unique index. The "result" attribute is a result object.

MongoDB::NotMasterError

This error indicates that a write or other state-modifying operation was attempted on a server that was not a primary. The "result" attribute is a MongoDB::CommandResult object.

MongoDB::WriteError

Errors indicating failure of a write command. The "result" attribute is a result object.

MongoDB::WriteConcernError

Errors indicating failure of a write concern. The "result" attribute is a result object.

MongoDB::DecodingError

This error indicates a problem during BSON decoding; it wraps the error provided by the underlying BSON encoder. Note: Encoding errors will be thrown as a "MongoDB::DocumentError".

MongoDB::DocumentError

This error indicates a problem with a document 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, such a corrupted file.

MongoDB::InternalError

Errors that indicate problems in the driver itself, typically when something unexpected is detected. These should be reported as potential bugs.

MongoDB::ProtocolError

Errors related to the MongoDB wire protocol, typically problems parsing a database response packet.

MongoDB::SelectionError

When server selection fails for a given operation, this is thrown. For example, attempting a write when no primary is available or reading with a specific mode and tag set and no servers match.

MongoDB::TimeoutError

These errors indicate a user-specified timeout has been exceeded.

MongoDB::ExecutionTimeout

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

MongoDB::NetworkTimeout

This error is thrown when a network operation exceeds a timeout, typically "connect_timeout_ms" or "socket_timeout_ms".

MongoDB::UsageError

Indicates invalid arguments or configuration options. Not all usage errors will throw this — only ones originating directly from the MongoDB::* library files. Some type and usage errors will originate from the Type::Tiny library if the objects are used incorrectly.

ERROR CODES

The following error code constants are automatically exported by this module. 

        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 error codes possible from the server, but covers some of the more common ones seen by drivers.

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.

AUTHORS

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

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004
2016-09-09 perl v5.24.1