Every app will eventually have to deal with an exception – runtime errors occur unexpectedly and your app must know how to deal with them and recover. It’s always good when error handling is transparent to the end-user but at the very least, good error handling should address the problem, give enough information to the user on what to do next, and exit the program gracefully. If you’ve put a lot of effort into writing your custom app, why let a runtime error ruin it all? This blog explains what the different return codes mean in libCouchbase derived clients (Ruby, PHP, Python, C/C++) and what your app should do when it encounters one.

Couchbase clients are smart. This means that they are cluster topology aware – if a node fails, the client is aware of this. If a new node is added to the cluster, the client is also aware of this new node. Compared to memcached clients, smart clients provide better performance and availability during failures by automatically routing requests to the correct Couchbase server.  Smart clients are either derived from libcouchbase (Ruby, Python, Perl, node.js and PHP) or are written in a native language such as Java and .NET. This blog will cover error codes returned by libcouchbase clients.

Applications use smart client API’s to send requests to Couchbase. Couchbase listens on 4 ports – 11210 (direct port), 11211 (proxy port), 8091(Admin console), and 8092 (couchbase views). Once connected, clients can send a stream of requests on the same connection to the server. Request messages typically include a memcached binary header of 24 bytes and a payload that is optional. The length of the payload is specified in the header. Document mutations first go to the object managed cache and then are replicated and persisted asynchronously. Couchbase returns a success (0) or failure (non-zero error code) as soon as the document is added to the object managed cache. The return code indicates the overall success or failure of the API call.

It is a good programming practice to check error codes in your application so that you know when retry the request or throw a user error. The table below list error codes in Couchbase and suggests what clients should do if they encounter an error that is listed :

If you’re using a client derived from libCouchbase such as Ruby, Python, Perl, node.js and PHP, following are some of the error codes you might see:

Error Code Received

What does it mean?

What should the client do?

LCB_SUCCESSOperation SucceededDo nothing. Couchbase successfully executed the client request.
LCB_AUTH_ERRORAuthentication failed. Invalid username or password was providedCheck the supplied username and password. Clients should retry with the correct username and password.


The operation cannot be executed with the requested arguments.Check the arguments and the operation executing on the arguments.

For example: Incrementing a non-numeric value  using the incr or incrementing by a non-numeric value

LCB_E2BIGServer reported that the object is too bigMax key size in Couchbase is 250 bytes. Maximum document size in Couchbase is 20Mb.


The client should retry and use objects with sizes within these limits.

LCB_EBUSYThe server is too busy to handle your requests right now.Use backoff in your app code and retry the operation again after some time.
LCB_EINTERNALThere is an internal error inside the library.Destroy the connection context and create a new one.
LCB_EINVALInvalid arguments specifiedMake sure you pass the correct arguments
LCB_ENOMEMThe server is out of memoryThis can occur during memory pressure when documents in memory are not yet flushed to disk. Backoff and retry after some time.
LCB_RANGEInvalid range specifiedPlease make sure you have specified proper ranges
LCB_ETMPFAILThe server tried to perform the operation but failed due to a temporary constraintBackoff and retry after some time.
LCB_KEY_EEXISTSThe key already exist (with another CAS value)Keys are unique in Couchbase. Try another key.
LCB_KEY_ENOENTThe key does not existThe key is not found. Try looking for another key.
LCB_NETWORK_ERRORA network related problem occurredTroubleshoot your network issue and retry.
LCB_NOT_MY_VBUCKETThe server, which received this request, is not responsible for this object anymore. This happens during cluster topology changes or rebalancing.The client automatically fetches a new cluster map from the server and learns about where it should send subsequent requests.


In libcouchbase, this error is not really exposed to the user. The library automatically manages reconnecting to the correct server.


Retry the operation again after some time.

LCB_NOT_STOREDThe object was not stored on the serverUse backoff in your app code and retry the operation again after some time.
LCB_NOT_SUPPORTEDThe server does not support the requested command.Check the request sent to the server.
LCB_UNKNOWN_COMMANDThe server does not know what the command is.Check the request sent to the server.
LCB_UNKNOWN_HOSTThe server failed to resolve the requested hostnameCheck the hostname specified.
LCB_PROTOCOL_ERRORThere is something wrong from the datastream received by the serverResult set should be discarded and not used. Client should retry the operation.
LCB_ETIMEOUTThe server operation timed outThis can occur if a server in the cluster fails and Couchbase yet has to detect this failure.

The client should retry after some time.

LCB_CONNECT_ERRORThe client failed to connect to the requested serverThe client should retry after some time.
LCB_BUCKET_ENOINTThe requested bucket does not existCheck if the bucket exists on the server and retry.
LCB_CLIENT_ENOMEMThe client ran out of memoryThis can occur if connection contexts are not freed properly on the client-side. Destroy current connection context and retry.
LCB_CLIENT_ETMPFAILThe client encountered a temporary error.The application can try again after some time.
LCB_SERVER_BUGUnexpected usage of server protocol caused unexpected results.Result set should be discarded and not used.


The developer should record his/her steps to reproduce the issue and file a bug.

LCB_INVALID_HOST_FORMATThe bootstrap host list used an invalid/unsupported format.Check the hostname format used, correct it and retry.
LCB_INVALID_CHARInvalid character used in the path component of a URLMake sure the URL path is encoded properly.

After receiving an error code from Couchbase, applications can convert these codes into a string – as shown in the example code snippet below, lcb_strerror() returns a 0-terminated string representing the error.

        #include <libcouchbase/couchbase.h>

        fprintf(stdout, “The textual string for LCB_SUCCESS is: %sn,
        lcb_strerror(NULL, LCB_SUCCESS));

No matter how confident you are, you cannot predict every problem you might can encounter. Without a mechanism to check for errors, you might think that Couchbase does not work properly. Make sure you check for error codes in your app so that you know why errors occur. 

Good luck building your apps on Couchbase!

Posted by Don Pinto, Principal Product Manager, Couchbase

Don Pinto is a Principal Product Manager at Couchbase and is currently focused on advancing the capabilities of Couchbase Server. He is extremely passionate about data technology, and in the past has authored several articles on Couchbase Server including technical blogs and white papers. Prior to joining Couchbase, Don spent several years at IBM where he maintained the role of software developer in the DB2 information management group and most recently as a program manager on the SQL Server team at Microsoft. Don holds a master's degree in computer science and a bachelor's in computer engineering from the University of Toronto, Canada.

One Comment

  1. […] my previous blog article, we looked at the errors thrown by libCouchbase clients such as ruby, python, C and C++. This blog […]

Leave a reply