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 NotFoundError:
    print("Item does not exist")
except CouchbaseTransientError:
    print("Transient error received. Handling and backing off")

Where NotFoundError is a specific error detail code indicating the item has not been found, and CouchbaseTransientError 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 CouchbaseError as e:
    if e.is_data and isinstance(e, NotFoundError):
        # 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.CouchbaseError(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 CouchbaseDataError)

is_transient¶

True if this error was likely caused by a transient condition (see CouchbaseTransientError)

is_fatal¶

True if this error indicates a likely fatal condition for the client. See CouchbaseFatalError

is_network¶

True if errors were received during TCP transport. See CouchbaseNetworkError

CODE¶

This is a _class_ level attribute which contains the equivalent libcouchbase error code which is mapped to this exception class.

This is usually the rc value for an exception instance. Unlike rc however, it may be used without an instantiated object, possibly helping performance.

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 `CouchbaseError`

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 CouchbaseTransientError 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.CouchbaseInternalError(params=None)[source]¶

exception couchbase.exceptions.CouchbaseNetworkError(params=None)[source]¶: Base class for network-related errors. These indicate issues in the low level connectivity

exception couchbase.exceptions.CouchbaseInputError(params=None)[source]¶: Base class for errors possibly caused by malformed input

exception couchbase.exceptions.CouchbaseFatalError(params=None)[source]¶: Base class for errors which are likely fatal and require reinitialization of the instance

exception couchbase.exceptions.CouchbaseDataError(params=None)[source]¶: Base class for negative replies received from the server. These errors indicate that the server could not satisfy the request because of certain data constraints (such as an item not being present, or a CAS mismatch)

exception couchbase.exceptions.CouchbaseTransientError(params=None)[source]¶: Base class for errors which are likely to go away with time

Exception Details¶

The following codes are exception details. They all derive from CouchbaseError. Many of them will have multiple error categories and thus be inherited from multiple exception categories.

exception couchbase.exceptions.ArgumentError(params=None)[source]¶

Bases: couchbase.exceptions.CouchbaseError

Invalid argument

A given argument is invalid or must be set

exception couchbase.exceptions.ValueFormatError(params=None)[source]¶

Bases: couchbase.exceptions.CouchbaseError

Failed to decode or encode value

exception couchbase.exceptions.AuthError(params=None)[source]¶

Bases: couchbase.exceptions.CouchbaseError

Authentication failed

You provided an invalid username/password combination.

exception couchbase.exceptions.DeltaBadvalError(params=None)[source]¶