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_SUCCESS Operation Succeeded Do nothing. Couchbase successfully executed the client request.
LCB_AUTH_ERROR Authentication failed. Invalid username or password was provided Check 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_E2BIG Server reported that the object is too big Max 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_EBUSY The 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_EINTERNAL There is an internal error inside the library. Destroy the connection context and create a new one.
LCB_EINVAL Invalid arguments specified Make sure you pass the correct arguments
LCB_ENOMEM The server is out of memory This can occur during memory pressure when documents in memory are not yet flushed to disk. Backoff and retry after some time.
LCB_RANGE Invalid range specified Please make sure you have specified proper ranges
LCB_ETMPFAIL The server tried to perform the operation but failed due to a temporary constraint Backoff and retry after some time.
LCB_KEY_EEXISTS The key already exist (with another CAS value) Keys are unique in Couchbase. Try another key.
LCB_KEY_ENOENT The key does not exist The key is not found. Try looking for another key.
LCB_NETWORK_ERROR A network related problem occurred Troubleshoot your network issue and retry.
LCB_NOT_MY_VBUCKET The 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_STORED The object was not stored on the server Use backoff in your app code and retry the operation again after some time.
LCB_NOT_SUPPORTED The server does not support the requested command. Check the request sent to the server.
LCB_UNKNOWN_COMMAND The server does not know what the command is. Check the request sent to the server.
LCB_UNKNOWN_HOST The server failed to resolve the requested hostname Check the hostname specified.
LCB_PROTOCOL_ERROR There is something wrong from the datastream received by the server Result set should be discarded and not used. Client should retry the operation.
LCB_ETIMEOUT The server operation timed out This 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_ERROR The client failed to connect to the requested server The client should retry after some time.
LCB_BUCKET_ENOINT The requested bucket does not exist Check if the bucket exists on the server and retry.
LCB_CLIENT_ENOMEM The client ran out of memory This can occur if connection contexts are not freed properly on the client-side. Destroy current connection context and retry.
LCB_CLIENT_ETMPFAIL The client encountered a temporary error. The application can try again after some time.
LCB_SERVER_BUG Unexpected 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_FORMAT The bootstrap host list used an invalid/unsupported format. Check the hostname format used, correct it and retry.
LCB_INVALID_CHAR Invalid character used in the path component of a URL Make 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