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:

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:

except CouchbaseException as e:
    if e.is_data and isinstance(e, DocumentNotFoundException):
        # handle not found
    elif e.is_network:
        print("Got network error")
    elif e.is_data:
        print("Got other data-related error")
        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


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)


If this exception was triggered by another exception, it is present here.


If applicable, this is the key which failed.


A tuple of (file, line) pointing to a location in the C source code where the exception was thrown (if applicable)


An integer representing a set of bits representing various error categories for the specific error as returned by libcouchbase.


True if this error is a negative reply from the server (see CouchbaseDataException)


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


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


True if errors were received during TCP transport. See CouchbaseNetworkException


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.

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


rc (int) – The error code received for an operation


a subclass of CouchbaseException


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

except CouchbaseTransientException as e:
    # Temporary failure or server OOM
    _, fail = e.split_results()

    # Sleep for a bit to reduce the load on the server

    # Try to add only the failed results again

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.


A tuple of ( ok, bad ) dictionaries.

Exception Categories

These categories form the base exception classes

exception couchbase.exceptions.CouchbaseInternalException(params=None)[source]
exception couchbase.exceptions.NetworkException(params=None)[source]

A generic network error

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 couchbase.exceptions.CouchbaseDataException(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.CouchbaseTransientException(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 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

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

Bases: couchbase.exceptions.KeyValueException

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

Bases: couchbase.exceptions.KeyValueException