Exception Objects¶
Exception Types and Classifiers¶
New in version 1.2.1.
Couchbase exceptions may be caught in two flavors. You can catch an exception either by its explicit subclass or by its base class.
Normally you should catch exception classes for cases you don’t have a specific handler for, and error details for things that need special handling. Thus for example:
try:
cb.get("foo")
except DocumentNotFoundException:
print("Item does not exist")
except CouchbaseTransientException:
print("Transient error received. Handling and backing off")
Where DocumentNotFoundException is a specific error detail code indicating the item has not been found, and CouchbaseTransientException is an error category indicating the specific cause is likely transient.
As your application evolves you may wish to examine the specific error code received as well as log the information to the screen.
Employing the error classifier pattern will prove scalable when additional error codes are added to the library. Sticking to catching error codes rather than specific error categories will allow your application to deal gracefully with future error codes so long as they match a specific category.
You may also employ a different use model, for example:
try:
cb.get("foo")
except CouchbaseException as e:
if e.is_data and isinstance(e, DocumentNotFoundException):
# handle not found
pass
elif e.is_network:
print("Got network error")
elif e.is_data:
print("Got other data-related error")
else:
print("Got unhandled error code")
Base Exception Object¶
This object is the base class for all exceptions thrown by Couchbase which are specific to the library. Other standard Python exceptions may still be thrown depending on the condition.
-
exception
couchbase.exceptions.
CouchbaseException
(params=None)[source]¶ Base exception for Couchbase errors
This is the base class for all exceptions thrown by Couchbase
Exception Attributes
-
rc
¶
The return code which caused the error
A
MultiResult
object, if this exception was thrown as part of a multi-operation. This contains all the operations (including ones which may not have failed)-
inner_cause
¶ If this exception was triggered by another exception, it is present here.
-
key
¶ If applicable, this is the key which failed.
-
csrc_info
¶ A tuple of (file, line) pointing to a location in the C source code where the exception was thrown (if applicable)
-
categories
¶ An integer representing a set of bits representing various error categories for the specific error as returned by libcouchbase.
-
is_data
¶ True if this error is a negative reply from the server (see
CouchbaseDataException
)
-
is_transient
¶ True if this error was likely caused by a transient condition (see
CouchbaseTransientException
)
-
is_fatal
¶ True if this error indicates a likely fatal condition for the client. See
CouchbaseFatalException
-
is_network
¶ True if errors were received during TCP transport. See
CouchbaseNetworkException
-
class
ParamType
() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)¶
-
property
categories
Gets the exception categories (as a set of bits)
-
classmethod
rc_to_exctype
(rc)[source]¶ Map an error code to an exception
- Parameters
rc (int) – The error code received for an operation
- Returns
a subclass of
CouchbaseException
-
split_results
()[source]¶ Convenience method to separate failed and successful results.
New in version 2.0.0.
This function will split the results of the failed operation (see
all_results
) into “good” and “bad” dictionaries.The intent is for the application to handle any successful results in a success code path, and handle any failed results in a “retry” code path. For example
try: cb.add_multi(docs) except CouchbaseTransientException as e: # Temporary failure or server OOM _, fail = e.split_results() # Sleep for a bit to reduce the load on the server time.sleep(0.5) # Try to add only the failed results again cb.add_multi(fail)
Of course, in the example above, the second retry may fail as well, and a more robust implementation is left as an exercise to the reader.
- Returns
A tuple of ( ok, bad ) dictionaries.
-
Exception Categories¶
These categories form the base exception classes
-
exception
couchbase.exceptions.
CouchbaseInputException
(params=None)[source]¶ Base class for errors possibly caused by malformed input
-
exception
couchbase.exceptions.
CouchbaseFatalException
(params=None)[source]¶ Base class for errors which are likely fatal and require reinitialization of the instance
Exception Details¶
The following codes are exception details. They all derive from
CouchbaseException
. Many of them will have multiple error categories and thus
be inherited from multiple exception categories.
-
exception
couchbase.exceptions.
InvalidArgumentException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Raised when It is unambiguously determined that the error was caused because of invalid arguments from the user Usually only thrown directly when doing request arg validation. Also commonly used as a parent class for many service-specific exceptions (see below)
-
exception
couchbase.exceptions.
ValueFormatException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Failed to decode or encode value
-
exception
couchbase.exceptions.
AuthenticationException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
An authorization failure is returned by the server for given resource and credentials. Message “An authorization error has occurred” Properties TBD
-
exception
couchbase.exceptions.
DeltaBadvalException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The given value is not a number
The server detected that operation cannot be executed with requested arguments. For example, when incrementing not a number.
-
exception
couchbase.exceptions.
TooBigException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Object too big
The server reported that this object is too big
-
exception
couchbase.exceptions.
BusyException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The cluster is too busy
The server is too busy to handle your request right now. please back off and try again at a later time.
-
exception
couchbase.exceptions.
InternalException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Internal Error
Internal error inside the library. You would have to destroy the instance and create a new one to recover.
-
exception
couchbase.exceptions.
InvalidException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Invalid arguments specified
-
exception
couchbase.exceptions.
NoMemoryException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The server ran out of memory
-
exception
couchbase.exceptions.
RangeException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
An invalid range specified
-
exception
couchbase.exceptions.
LibcouchbaseException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
A generic error
-
exception
couchbase.exceptions.
TemporaryFailException
(params=None)[source]¶ Bases:
couchbase.exceptions.SharedException
Temporary failure (on server)
The server tried to perform the requested operation, but failed due to a temporary constraint. Retrying the operation may work.
This error may also be delivered if the key being accessed was locked.
See also
couchbase_core.client.Client.lock()
couchbase_core.client.Client.unlock()
-
exception
couchbase.exceptions.
DocumentExistsException
(params=None)[source]¶ Bases:
couchbase.exceptions.KeyValueException
-
exception
couchbase.exceptions.
DocumentNotFoundException
(params=None)[source]¶ Bases:
couchbase.exceptions.KeyValueException
-
exception
couchbase.exceptions.
DlopenFailedException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Failed to open shared object
-
exception
couchbase.exceptions.
DlsymFailedException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Failed to locate the requested symbol in the shared object
-
exception
couchbase.exceptions.
NetworkException
(params=None)[source] Bases:
couchbase.exceptions.CouchbaseException
A generic network error
-
exception
couchbase.exceptions.
NotMyVbucketException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The vbucket is not located on this server
The server who received the request is not responsible for the object anymore. (This happens during changes in the cluster topology)
-
exception
couchbase.exceptions.
NotStoredException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The object was not stored on the server
-
exception
couchbase.exceptions.
NotSupportedException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Not supported
The server doesn’t support the requested command. This error differs from
UnknownCommandException
by that the server knows about the command, but for some reason decided to not support it.
-
exception
couchbase.exceptions.
UnknownCommandException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The server doesn’t know what that command is
-
exception
couchbase.exceptions.
UnknownHostException
(params=None)[source]¶ Bases:
couchbase.exceptions.NetworkException
The server failed to resolve the requested hostname
-
exception
couchbase.exceptions.
ProtocolException
(params=None)[source]¶ Bases:
couchbase.exceptions.NetworkException
Protocol error
There is something wrong with the datastream received from the server
-
exception
couchbase.exceptions.
TimeoutException
(params=None)[source]¶ Bases:
couchbase.exceptions.SharedException
— Message Properties Reason: (Exception) Explains the underlying reason we expect this was caused.
-
exception
couchbase.exceptions.
ConnectException
(params=None)[source]¶ Bases:
couchbase.exceptions.NetworkException
Failed to connect to the requested server
-
exception
couchbase.exceptions.
BucketNotFoundException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The requested bucket does not exist
-
exception
couchbase.exceptions.
ClientNoMemoryException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
The client ran out of memory
-
exception
couchbase.exceptions.
ClientTemporaryFailException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Temporary failure (on client)
The client encountered a temporary error (retry might resolve the problem)
-
exception
couchbase.exceptions.
BadHandleException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
Invalid handle type
The requested operation isn’t allowed for given type.
-
exception
couchbase.exceptions.
HTTPException
(params=None)[source]¶ Bases:
couchbase.exceptions.CouchbaseException
HTTP error