.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "MongoDB::Error 3pm" .TH MongoDB::Error 3pm "2016-09-09" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MongoDB::Error \- MongoDB Driver Error classes .SH "VERSION" .IX Header "VERSION" version v1.4.5 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 6 \& use MongoDB::Error; \& MongoDB::Error\->throw("a generic error"); \& MongoDB::DatabaseError\->throw( \& message => $string, \& result => $hashref, \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class defines a hierarchy of exception objects. .SH "USAGE" .IX Header "USAGE" Unless otherwise explicitly documented, all driver methods throw exceptions if an error occurs. .PP To catch and handle errors, the Try::Tiny and Safe::Isa modules are recommended: .PP .Vb 2 \& use Try::Tiny; \& use Safe::Isa; # provides $_isa \& \& try { \& $coll\->insert( $doc ) \& } \& catch { \& if ( $_\->$_isa("MongoDB::DuplicateKeyError" ) ) { \& ... \& } \& else { \& ... \& } \& }; .Ve .PP To retry failures automatically, consider using Try::Tiny::Retry. .SH "EXCEPTION HIERARCHY" .IX Header "EXCEPTION HIERARCHY" .Vb 10 \& 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 .Ve .PP All classes inherit from \f(CW\*(C`MongoDB::Error\*(C'\fR. .PP All error classes have the attribute: .IP "\(bu" 4 message — a text representation of the error .SS "MongoDB::AuthError" .IX Subsection "MongoDB::AuthError" This error indicates a problem with authentication, either in the underlying mechanism or a problem authenticating with the server. .SS "MongoDB::ConnectionError" .IX Subsection "MongoDB::ConnectionError" Errors related to network connections. .PP \fIMongoDB::HandshakeError\fR .IX Subsection "MongoDB::HandshakeError" .PP This error is thrown when a connection has been made, but \s-1SSL\s0 or authentication handshakes fail. .PP \fIMongoDB::NetworkError\fR .IX Subsection "MongoDB::NetworkError" .PP This error is thrown when a socket error occurs, when the wrong number of bytes are read, or other wire-related errors occur. .SS "MongoDB::CursorNotFoundError" .IX Subsection "MongoDB::CursorNotFoundError" This error indicates that a cursor timed out on a server. .SS "MongoDB::DatabaseError" .IX Subsection "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. .PP Attributes include: .IP "\(bu" 4 result — response from a database command; this must impliement the \f(CW\*(C`last_errmsg\*(C'\fR method .IP "\(bu" 4 code — numeric error code; see \*(L"\s-1ERROR CODES\*(R"\s0; if no code was provided by the database, the \f(CW\*(C`UNKNOWN_ERROR\*(C'\fR code will be substituted instead .PP \fIMongoDB::DuplicateKeyError\fR .IX Subsection "MongoDB::DuplicateKeyError" .PP This error indicates that a write attempted to create a document with a duplicate key in a collection with a unique index. The \f(CW\*(C`result\*(C'\fR attribute is a result object. .PP \fIMongoDB::NotMasterError\fR .IX Subsection "MongoDB::NotMasterError" .PP This error indicates that a write or other state-modifying operation was attempted on a server that was not a primary. The \f(CW\*(C`result\*(C'\fR attribute is a MongoDB::CommandResult object. .PP \fIMongoDB::WriteError\fR .IX Subsection "MongoDB::WriteError" .PP Errors indicating failure of a write command. The \f(CW\*(C`result\*(C'\fR attribute is a result object. .PP \fIMongoDB::WriteConcernError\fR .IX Subsection "MongoDB::WriteConcernError" .PP Errors indicating failure of a write concern. The \f(CW\*(C`result\*(C'\fR attribute is a result object. .SS "MongoDB::DecodingError" .IX Subsection "MongoDB::DecodingError" This error indicates a problem during \s-1BSON\s0 decoding; it wraps the error provided by the underlying \s-1BSON\s0 encoder. Note: Encoding errors will be thrown as a \*(L"MongoDB::DocumentError\*(R". .SS "MongoDB::DocumentError" .IX Subsection "MongoDB::DocumentError" This error indicates a problem with a document to be inserted or replaced into the database, or used as an update document. .PP Attributes include: .IP "\(bu" 4 document — the document that caused the error .SS "MongoDB::GridFSError" .IX Subsection "MongoDB::GridFSError" Errors related to GridFS operations, such a corrupted file. .SS "MongoDB::InternalError" .IX Subsection "MongoDB::InternalError" Errors that indicate problems in the driver itself, typically when something unexpected is detected. These should be reported as potential bugs. .SS "MongoDB::ProtocolError" .IX Subsection "MongoDB::ProtocolError" Errors related to the MongoDB wire protocol, typically problems parsing a database response packet. .SS "MongoDB::SelectionError" .IX Subsection "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. .SS "MongoDB::TimeoutError" .IX Subsection "MongoDB::TimeoutError" These errors indicate a user-specified timeout has been exceeded. .PP \fIMongoDB::ExecutionTimeout\fR .IX Subsection "MongoDB::ExecutionTimeout" .PP This error is thrown when a query or command fails because \f(CW\*(C`max_time_ms\*(C'\fR has been reached. The \f(CW\*(C`result\*(C'\fR attribute is a MongoDB::CommandResult object. .PP \fIMongoDB::NetworkTimeout\fR .IX Subsection "MongoDB::NetworkTimeout" .PP This error is thrown when a network operation exceeds a timeout, typically \&\f(CW\*(C`connect_timeout_ms\*(C'\fR or \f(CW\*(C`socket_timeout_ms\*(C'\fR. .SS "MongoDB::UsageError" .IX Subsection "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. .SH "ERROR CODES" .IX Header "ERROR CODES" The following error code constants are automatically exported by this module. .PP .Vb 10 \& 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, .Ve .PP 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. .PP \&\fBNote\fR: .IP "\(bu" 4 Only \f(CW\*(C`MongoDB::DatabaseError\*(C'\fR objects have a \f(CW\*(C`code\*(C'\fR attribute. .IP "\(bu" 4 The database uses multiple write concern error codes. The driver maps them all to \s-1WRITE_CONCERN_ERROR\s0 for consistency and convenience. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Mike Friedman .IP "\(bu" 4 Kristina Chodorow .IP "\(bu" 4 Florian Ragwitz .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2016 by MongoDB, Inc. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve