1MongoDB::Error(3)     User Contributed Perl Documentation    MongoDB::Error(3)
2
3
4

NAME

6       MongoDB::Error - MongoDB Driver Error classes
7

VERSION

9       version v2.2.2
10

SYNOPSIS

12           use MongoDB::Error;
13           MongoDB::Error->throw("a generic error");
14           MongoDB::DatabaseError->throw(
15               message => $string,
16               result => $hashref,
17           );
18

DESCRIPTION

20       This class defines a hierarchy of exception objects.
21

USAGE

23       Unless otherwise explicitly documented, all driver methods throw
24       exceptions if an error occurs.
25
26       To catch and handle errors, the Try::Tiny and Safe::Isa modules are
27       recommended:
28
29           use Try::Tiny;
30           use Safe::Isa; # provides $_isa
31
32           try {
33               $coll->insert( $doc )
34           }
35           catch {
36               if ( $_->$_isa("MongoDB::DuplicateKeyError" ) ) {
37                   ...
38               }
39               else {
40                   ...
41               }
42           };
43
44       To retry failures automatically, consider using Try::Tiny::Retry.
45

EXCEPTION HIERARCHY

47           MongoDB::Error
48               |
49               |->MongoDB::AuthError
50               |
51               |->MongoDB::ConnectionError
52               |   |
53               |   |->MongoDB::HandshakeError
54               |   |
55               |   |->MongoDB::NetworkError
56               |
57               |->MongoDB::ConfigurationError
58               |
59               |->MongoDB::DatabaseError
60               |   |
61               |   |->MongoDB::CursorNotFoundError
62               |   |
63               |   |->MongoDB::DuplicateKeyError
64               |   |
65               |   |->MongoDB::NotMasterError
66               |   |
67               |   |->MongoDB::WriteError
68               |   |
69               |   |->MongoDB::WriteConcernError
70               |
71               |->MongoDB::DecodingError
72               |
73               |->MongoDB::DocumentError
74               |
75               |->MongoDB::GridFSError
76               |
77               |->MongoDB::InternalError
78               |
79               |->MongoDB::InvalidOperationError
80               |
81               |->MongoDB::ProtocolError
82               |
83               |->MongoDB::SelectionError
84               |
85               |->MongoDB::TimeoutError
86               |   |
87               |   |->MongoDB::ExecutionTimeout
88               |   |
89               |   |->MongoDB::NetworkTimeout
90               |
91               |->MongoDB::UsageError
92
93       All classes inherit from "MongoDB::Error".
94
95       All error classes have the attribute:
96
97       •   message — a text representation of the error
98
99   MongoDB::AuthError
100       This error indicates a problem with authentication, either in the
101       underlying mechanism or a problem authenticating with the server.
102
103   MongoDB::ConnectionError
104       Errors related to network connections.
105
106       MongoDB::HandshakeError
107
108       This error is thrown when a connection has been made, but SSL or
109       authentication handshakes fail.
110
111       MongoDB::NetworkError
112
113       This error is thrown when a socket error occurs, when the wrong number
114       of bytes are read, or other wire-related errors occur.
115
116   MongoDB::ConfigurationError
117       This error is thrown when there is a configuration error between the
118       MongoDB deployment and the configuration of the client, such as when
119       trying to use explicit sessions on a MongoDB < 3.6
120
121   MongoDB::CursorNotFoundError
122       This error indicates that a cursor timed out on a server.
123
124   MongoDB::DatabaseError
125       Errors related to database operations.  Specifically, when an error of
126       this type occurs, the driver has received an error condition from the
127       server.
128
129       Attributes include:
130
131       •   result — response from a database command; this must implement the
132           "last_errmsg" method
133
134       •   code — numeric error code; see "ERROR CODES"; if no code was
135           provided by the database, the "UNKNOWN_ERROR" code will be
136           substituted instead
137
138       MongoDB::DuplicateKeyError
139
140       This error indicates that a write attempted to create a document with a
141       duplicate key in a collection with a unique index.  The "result"
142       attribute is a result object.
143
144       MongoDB::NotMasterError
145
146       This error indicates that a write or other state-modifying operation
147       was attempted on a server that was not a primary.  The "result"
148       attribute is a MongoDB::CommandResult object.
149
150       MongoDB::WriteError
151
152       Errors indicating failure of a write command.  The "result" attribute
153       is a result object.
154
155       MongoDB::WriteConcernError
156
157       Errors indicating failure of a write concern.  The "result" attribute
158       is a result object.
159
160   MongoDB::DecodingError
161       This error indicates a problem during BSON decoding; it wraps the error
162       provided by the underlying BSON encoder.  Note: Encoding errors will be
163       thrown as a "MongoDB::DocumentError".
164
165   MongoDB::DocumentError
166       This error indicates a problem with a document to be inserted or
167       replaced into the database, or used as an update document.
168
169       Attributes include:
170
171       •   document — the document that caused the error
172
173   MongoDB::GridFSError
174       Errors related to GridFS operations, such a corrupted file.
175
176   MongoDB::InternalError
177       Errors that indicate problems in the driver itself, typically when
178       something unexpected is detected.  These should be reported as
179       potential bugs.
180
181   MongoDB::ProtocolError
182       Errors related to the MongoDB wire protocol, typically problems parsing
183       a database response packet.
184
185   MongoDB::SelectionError
186       When server selection fails for a given operation, this is thrown. For
187       example, attempting a write when no primary is available or reading
188       with a specific mode and tag set and no servers match.
189
190   MongoDB::TimeoutError
191       These errors indicate a user-specified timeout has been exceeded.
192
193       MongoDB::ExecutionTimeout
194
195       This error is thrown when a query or command fails because
196       "max_time_ms" has been reached.  The "result" attribute is a
197       MongoDB::CommandResult object.
198
199       MongoDB::NetworkTimeout
200
201       This error is thrown when a network operation exceeds a timeout,
202       typically "connect_timeout_ms" or "socket_timeout_ms".
203
204   MongoDB::UsageError
205       Indicates invalid arguments or configuration options.  Not all usage
206       errors will throw this — only ones originating directly from the
207       MongoDB::* library files.  Some type and usage errors will originate
208       from the Type::Tiny library if the objects are used incorrectly.
209
210       Also used to indicate usage errors for transaction commands.
211

ERROR CODES

213       The following error code constants are automatically exported by this
214       module.
215
216               BAD_VALUE                 => 2,
217               UNKNOWN_ERROR             => 8,
218               NAMESPACE_NOT_FOUND       => 26,
219               EXCEEDED_TIME_LIMIT       => 50,
220               COMMAND_NOT_FOUND         => 59,
221               WRITE_CONCERN_ERROR       => 64,
222               NOT_MASTER                => 10107,
223               DUPLICATE_KEY             => 11000,
224               DUPLICATE_KEY_UPDATE      => 11001, # legacy before 2.6
225               DUPLICATE_KEY_CAPPED      => 12582, # legacy before 2.6
226               UNRECOGNIZED_COMMAND      => 13390, # mongos error before 2.4
227               NOT_MASTER_NO_SLAVE_OK    => 13435,
228               NOT_MASTER_OR_SECONDARY   => 13436,
229               CANT_OPEN_DB_IN_READ_LOCK => 15927,
230
231       This is a very, very small subset of error codes possible from the
232       server, but covers some of the more common ones seen by drivers.
233
234       Note:
235
236       •   Only "MongoDB::DatabaseError" objects have a "code" attribute.
237
238       •   The database uses multiple write concern error codes.  The driver
239           maps them all to WRITE_CONCERN_ERROR for consistency and
240           convenience.
241

ERROR LABELS

243       From MongoDB 4.0 onwards, errors may contain an error labels field.
244       This field is populated for extra information from either the server or
245       the driver, depending on the error.
246
247       Known error labels include (but are not limited to):
248
249       •   "TransientTransactionError" - added when network errors are
250           encountered inside a transaction.
251
252       •   "UnknownTransactionCommitResult" - added when a transaction commit
253           may not have been able to satisfy the provided write concern.
254

AUTHORS

256       •   David Golden <david@mongodb.com>
257
258       •   Rassi <rassi@mongodb.com>
259
260       •   Mike Friedman <friedo@friedo.com>
261
262       •   Kristina Chodorow <k.chodorow@gmail.com>
263
264       •   Florian Ragwitz <rafl@debian.org>
265
267       This software is Copyright (c) 2020 by MongoDB, Inc.
268
269       This is free software, licensed under:
270
271         The Apache License, Version 2.0, January 2004
272
273
274
275perl v5.36.0                      2023-01-20                 MongoDB::Error(3)
Impressum