Blog Post

Handling Runtime Errors in Ruby, Python and C Clients

Don Pinto of Couchbase Published

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.

LCB_DELTA_BADVAL


 

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: %s\n",
 
        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!