A newer version of this documentation is available.

View Latest

Handling Exceptions

Python exceptions are thrown when an error is encountered. In the Couchbase Python SDK, exceptions are structured in a class hierarchy, with each exception belonging to one or more categories (in the form of base classes):

All Couchbase exceptions are derived from CouchbaseError. Exceptions may be caught via except. You may catch specific exceptions for specific handling, or you may catch the CouchbaseError and handle exceptions based on their status codes.


This error category is raised when there is a data logic error (for example, a missing document ID). Handling of this error depends on application logic (for example, either perform corrective action to insert the document, or return an error up the stack indicating the specified resource does not exist).

Read more about data errors here: Data errors


This type of exception is thrown during argument/input validation. It indicates that one or more arguments passed to a method are invalid. You should determine how and why the application is passing invalid input to the SDK

CouchbaseNetworkError and CouchbaseTransientError

This error category indicates a connectivity issue between the SDK and the Couchbase Cluster. This error might be a result of a temporary condition or a systematic infrastructure failure. See Transient and resource errors.

TimeoutError and NetworkError are subclasses of these error types.

One noteworthy corrective action is performing a replica read if attempting to retrieve a document from an unreachable server.


This error is thrown when access is detected from multiple concurrent threads. See Using threads for information on configuring the SDK in a threaded Python application.

Anatomy of an exception object

The Python SDK makes full use of the fact that a Python exception is just an object. In addition to catching the exception itself, the exception object may be analyzed for more information regarding the failure, and in the case of batched operations, may be inspected to determine which operations failed and which succeeded.

Applications may use the is_data property on a CouchbaseError instance to determine if the error is a negative reply from the server; the property will evaluate to True for situations where a key is not found, already exists, and so on. Likewise applications may use the is_network property to determine if the exception is a result of a potential network issue (and is thus not an issue with the data, but rather an issue concerning the connectivity between client and server).

All exceptions which are either data errors or network errors will contain a non-zero status code from the underlying C library; this status code may be obtained using the rc property of the exception. Exceptions which contain an rc value of 0 are typically ArgumentErrors which are thrown when a method was supplied with an invalid parameter, or an invalid combination of parameters.