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.
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!