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 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:

except CouchbaseError as e:
    if e.is_data and isinstance(e, NotFoundError):
        # 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.CouchbaseError(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 CouchbaseDataError)


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


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


True if errors were received during TCP transport. See CouchbaseNetworkError


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.

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 CouchbaseError


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 CouchbaseTransientError 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.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_core.exceptions.CouchbaseError

Invalid argument

A given argument is invalid or must be set

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

Bases: couchbase_core.exceptions.CouchbaseError

Failed to decode or encode value

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

Bases: couchbase_core.exceptions.CouchbaseError

Authentication failed

You provided an invalid username/password combination.

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

Bases: couchbase_core.exceptions.CouchbaseError

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

Bases: couchbase_core.exceptions.CouchbaseError

Object too big

The server reported that this object is too big

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

Bases: couchbase_core.exceptions.CouchbaseError

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

Bases: couchbase_core.exceptions.CouchbaseError

Internal Error

Internal error inside the library. You would have to destroy the instance and create a new one to recover.

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

Bases: couchbase_core.exceptions.CouchbaseError

Invalid arguments specified

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

Bases: couchbase_core.exceptions.CouchbaseError

The server ran out of memory

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

Bases: couchbase_core.exceptions.CouchbaseError

An invalid range specified

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

Bases: couchbase_core.exceptions.CouchbaseError

A generic error

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

Bases: couchbase_core.exceptions.CouchbaseError

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.bucket.Bucket.lock() couchbase_core.bucket.Bucket.unlock()

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

Bases: couchbase_core.exceptions.CouchbaseError

The key already exists (with another CAS value)

This exception may be thrown during an add() operation (if the key already exists), or when a CAS is supplied and the server-side CAS differs.

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

Bases: couchbase_core.exceptions.CouchbaseError

The key does not exist

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

Bases: couchbase_core.exceptions.CouchbaseError

Failed to open shared object

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

Bases: couchbase_core.exceptions.CouchbaseError

Failed to locate the requested symbol in the shared object

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

Bases: couchbase_core.exceptions.CouchbaseNetworkError

Network error

A network related problem occured (name lookup, read/write/connect etc)

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

Bases: couchbase_core.exceptions.CouchbaseError

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

Bases: couchbase_core.exceptions.CouchbaseError

The object was not stored on the server

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

Bases: couchbase_core.exceptions.CouchbaseError

Not supported

The server doesn’t support the requested command. This error differs from couchbase_core.exceptions.UnknownCommandError by that the server knows about the command, but for some reason decided to not support it.

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

Bases: couchbase_core.exceptions.CouchbaseError

The server doesn’t know what that command is

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

Bases: couchbase_core.exceptions.CouchbaseNetworkError

The server failed to resolve the requested hostname

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

Bases: couchbase_core.exceptions.CouchbaseNetworkError

Protocol error

There is something wrong with the datastream received from the server

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

Bases: couchbase_core.exceptions.CouchbaseError

The operation timed out

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

Bases: couchbase_core.exceptions.CouchbaseNetworkError

Failed to connect to the requested server

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

Bases: couchbase_core.exceptions.CouchbaseError

The requested bucket does not exist

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

Bases: couchbase_core.exceptions.CouchbaseError

The client ran out of memory

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

Bases: couchbase_core.exceptions.CouchbaseError

Temporary failure (on client)

The client encountered a temporary error (retry might resolve the problem)

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

Bases: couchbase_core.exceptions.CouchbaseError

Invalid handle type

The requested operation isn’t allowed for given type.

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

Bases: couchbase_core.exceptions.CouchbaseError

HTTP error

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

Bases: couchbase_core.exceptions.CouchbaseError

Subdocument path does not exist

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

Bases: couchbase_core.exceptions.CouchbaseError

Subdocument path already exists (and shouldn’t)