Couchbase C Client  2.9.5
Asynchronous C Client for Couchbase
Error Codes

Detailed Description

Status codes returned by the library.

Functions

int lcb_get_errtype (lcb_error_t err)
 
Get error categories for a specific code More...
 
const char * lcb_strerror (lcb_t instance, lcb_error_t error)
 
Get a textual descrtiption for the given error code More...
 
LCB_INTERNAL_API const char * lcb_strerror_short (lcb_error_t error)
 Get a shorter textual description of an error message. More...
 
LCB_INTERNAL_API const char * lcb_strerror_long (lcb_error_t error)
 Get a longer textual description of an error message.
 
lcb_error_t lcb_errmap_default (lcb_t instance, lcb_U16 code)
 
This may be used in conjunction with the errmap callback if it wishes to fallback for default behavior for the given code. More...
 
lcb_errmap_callback lcb_set_errmap_callback (lcb_t, lcb_errmap_callback)
 

Macros

#define LCB__ERR_USEDETAILS
 
#define LCB_XERR(X)
 XMacro for all error types. More...
 
#define LCB_CLIENT_ETMPFAIL
 
#define LCB_EIFINPUT(e)
 If the error is a result of bad input.
 
#define LCB_EIFNET(e)
 if the error is a result of a network condition
 
#define LCB_EIFFATAL(e)
 if the error is fatal
 
#define LCB_EIFTMP(e)
 if the error is transient
 
#define LCB_EIFDATA(e)
 if the error is a routine negative server reply
 
#define LCB_EIFPLUGIN(e)
 if the error is a result of a plugin implementation
 
#define LCB_EIFSRVLOAD(e)
 
#define LCB_EIFSRVGEN(e)
 
#define LCB_EIFSUBDOC(e)
 

Typedefs

typedef lcb_error_t(* lcb_errmap_callback) (lcb_t instance, lcb_U16 bincode)
 Callback for error mappings. More...
 

Enumerations

enum  lcb_errflags_t
 Error Categories. More...
 
enum  lcb_error_t
 Error codes returned by the library. More...
 

Function Documentation

◆ lcb_get_errtype()

int lcb_get_errtype ( lcb_error_t  err)


Get error categories for a specific code

Parameters
errthe error received
Returns
a set of flags containing the categories for the given error
Stability
Committed:

◆ lcb_strerror()

const char* lcb_strerror ( lcb_t  instance,
lcb_error_t  error 
)


Get a textual descrtiption for the given error code

Parameters
instancethe instance the error code belongs to (you might want different localizations for the different instances)
errorthe error code
Returns
A textual description of the error message. The caller should not release the memory returned from this function.
Stability
Committed:
Examples:
example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/observe/durability.c, example/observe/observe.c, example/subdoc/subdoc-xattrs.c, example/tracing/tracing.c, and example/tracing/views.c.

◆ lcb_strerror_short()

LCB_INTERNAL_API const char* lcb_strerror_short ( lcb_error_t  error)

Get a shorter textual description of an error message.

This is the constant name

Examples:
example/analytics/analytics.c, example/fts/fts.c, and example/minimal/query.c.

◆ lcb_errmap_default()

lcb_error_t lcb_errmap_default ( lcb_t  instance,
lcb_U16  code 
)


This may be used in conjunction with the errmap callback if it wishes to fallback for default behavior for the given code.

Stability
Uncommitted:

◆ lcb_set_errmap_callback()

lcb_errmap_callback lcb_set_errmap_callback ( lcb_t  ,
lcb_errmap_callback   
)
Stability
Uncommitted:

Macro Definition Documentation

◆ LCB_XERR

#define LCB_XERR (   X)

XMacro for all error types.

Parameters
Xmacro to be invoked for each function. This will accept the following arguments:
  • Raw unquoted literal error identifier (e.g. LCB_EINVAL)
  • Code for the error (e.g. 0x23)
  • Set of categories for the specific error (e.g. LCB_ERRTYPE_FOO|LCB_ERRTYPE_BAR)
  • Quoted string literal describing the error (e.g. "This is sad")

◆ LCB_CLIENT_ETMPFAIL

#define LCB_CLIENT_ETMPFAIL
Deprecated:
Use new, less ambiguous identifier (LCB_CLIENT_ENOCONF)

Typedef Documentation

◆ lcb_errmap_callback

typedef lcb_error_t(* lcb_errmap_callback) (lcb_t instance, lcb_U16 bincode)

Callback for error mappings.

This will be invoked when requesting whether the user has a possible mapping for this error code.

This will be called for response codes which may be ambiguous in most use cases, or in cases where detailed response codes may be mapped to more generic ones.

Enumeration Type Documentation

◆ lcb_errflags_t

Error Categories.

These error categories are assigned as a series of OR'd bits to each of the error codes in lcb_error_t.

See also
lcb_get_errtype
Enumerator
LCB_ERRTYPE_INPUT 

Error type indicating a likely issue in user input.

LCB_ERRTYPE_NETWORK 

Error type indicating a likely network failure.

LCB_ERRTYPE_FATAL 

Error type indicating a fatal condition within the server or library.

LCB_ERRTYPE_TRANSIENT 

Error type indicating a transient condition within the server.

LCB_ERRTYPE_DATAOP 

Error type indicating a negative server reply for the data.

LCB_ERRTYPE_INTERNAL 

Error codes which should never be visible to the user.

LCB_ERRTYPE_PLUGIN 

Error code indicating a plugin failure.

LCB_ERRTYPE_SRVLOAD 

Error code indicating the server is under load.

LCB_ERRTYPE_SRVGEN 

Error code indicating the server generated this message.

LCB_ERRTYPE_SUBDOC 

Error code indicates document (fulldoc) access ok, but error in performing subdocument operation.

Note that this only covers errors which relate to a specific operation, rather than operations which prevent any subdoc operation from executing.

◆ lcb_error_t

Error codes returned by the library.

Enumerator
LCB_SUCCESS 

Success.

LCB_AUTH_ERROR 

This error code is received in callbacks when connecting or reconnecting to the cluster.

If received during initial bootstrap (i.e. lcb_get_bootstrap_status()) then it should be considered a fatal errror. This error should not be visible after initial bootstrap. This error may also be received if CCCP bootstrap is used and the bucket does not exist.

LCB_DELTA_BADVAL 

This error is received in callbacks.

It is a result of trying to perform an lcb_arithmetic() operation on an item which has an existing value that cannot be parsed as a number.

LCB_E2BIG 

This error is received in callbacks.

It indicates that the key and value exceeded the constraints within the server. The current constraints are 150 bytes for a key and 20MB for a value

LCB_EINTERNAL 

Internal error within the library.

This may be a result of a bug

LCB_EINVAL 

If returned from an API call, it indicates invalid values were passed to the function.

If received within a callback, it indicates that a malformed packet was sent to the server.

LCB_ENOMEM 

This code is received in callbacks.

It means the server has no more memory left to store or modify the item.

LCB_ERROR 

Generic error.

LCB_ETMPFAIL 

This error is received in callbacks from the server itself to indicate that it could not perform the requested operation.

This is usually due to memory and/or resource constraints on the server. This error may also be returned if a key has been locked (see lcb_get()) and an operation has been performed on it without unlocking the item (see lcb_unlock(), or pass the correct CAS value to a mutation function).

LCB_KEY_EEXISTS 

The key already exists in the cluster.

This error code is received within callbacks as a result of an add operation in which the key already exists. It is also received for other operations in which a CAS was specified but has changed on the server.

LCB_KEY_ENOENT 

Received in callbacks to indicate that the server does not contain the item.

LCB_DLOPEN_FAILED 

Error code thrown if an I/O plugin could not be located.

LCB_DLSYM_FAILED 

Error code thrown of an I/O plugin did not contain a proper initialization routine.

LCB_NETWORK_ERROR 

This is a generic error code returned for various forms of socket operation failures.

Newer applications are recommended to enable the LCB_CNTL_DETAILED_ERRCODES setting via lcb_cntl() and receive more detailed information about a socket error.

See also
lcb_cntl(), LCB_CNTL_DETAILED_ERRCODES
LCB_NOT_MY_VBUCKET 

Error code received in callbacks if the command was forwarded to the wrong server (for example, during a rebalance) and the library settings are configured that the command should not be remapped to a new server.

LCB_NOT_STORED 

Received in callbacks as a response to an LCB_APPEND or LCB_PREPEND on an item that did not exist in the cluster.

Equivalent to LCB_KEY_ENOENT

LCB_NOT_SUPPORTED 

Returned from API calls if a specific operation is valid but is unsupported in the current version or state of the library.

May also be received in a callback if the cluster does not support the operation. This will be returned for unknown settings passed to lcb_cntl() unless LCB_CNTL_DETAILED_ERRCODES is set

LCB_UNKNOWN_COMMAND 

Received in callbacks if the cluster does not know about the command.

Similar to LCB_NOT_SUPPORTED

LCB_UNKNOWN_HOST 

Error code received if the hostname specified could not be found.

It may also be received if a socket could not be created to the host supplied. A more detailed error code may be returned instead if LCB_CNTL_DETAILED_ERRCODES is set.

LCB_PROTOCOL_ERROR 

Error code received if the server replied with an unexpected response.

LCB_ETIMEDOUT 

Error code received in callbacks for operations which did not receive a reply from the server within the timeout limit.

See also
LCB_CNTL_OP_TIMEOUT
LCB_CONNECT_ERROR 
See also
LCB_NETWORK_ERROR, LCB_UNKNOWN_HOST, LCB_CNTL_DETAILED_ERRCODES
LCB_BUCKET_ENOENT 

Received on initial bootstrap if the bucket does not exist.

Note that for CCCP bootstrap, LCB_AUTH_ERROR will be received instead

LCB_CLIENT_ENOMEM 

Client could not allocate memory for internal structures.

LCB_CLIENT_ENOCONF 

Client could not schedule the request.

This is typically received when an operation is requested before the initial bootstrap has completed

LCB_DURABILITY_ETOOMANY 

Received in response to the durability API call, if the amount of nodes or replicas to persist/replicate to exceed the total number of replicas the bucket was configured with.

LCB_DUPLICATE_COMMANDS 

Received in scheduling if a command with the same key was specified more than once.

Some commands will accept this, but others (notably observe) will not

LCB_NO_MATCHING_SERVER 

This error is received from API calls if the master node for the vBucket the key has been hashed to is not present.

This will happen in the result of a node failover where no replica exists to replace it.

LCB_BAD_ENVIRONMENT 

Received during initial creation (lcb_create()) if an environment variable was specified with an incorrect or invalid value.

See also
Environment Variables
LCB_INVALID_USERNAME 

Received from lcb_create() if the username does not match the bucket.

LCB_SASLMECH_UNAVAILABLE 

Received during initial bootstrap if the library was configured to force the usage of a specific SASL mechanism and the server did not support this mechanism.

See also
LCB_CNTL_FORCE_SASL_MECH
LCB_TOO_MANY_REDIRECTS 

Received in the HTTP callback if the response was redirected too many times.

See also
LCB_CNTL_MAX_REDIRECTS
LCB_MAP_CHANGED 

May be received in operation callbacks if the cluster toplogy changed and the library could not remap the command to a new node.

This may be because the internal structure lacked sufficient information to recreate the packet, or because the configuration settings indicated that the command should not be retried.

See also
LCB_CNTL_RETRYMODE
LCB_INCOMPLETE_PACKET 

Returned from the lcb_pktfwd3() function if an incomplete packet was passed.

LCB_ECONNREFUSED 

Mapped directly to the system ECONNREFUSED errno.

This is received in callbacks if an initial connection to the node could not be established. Check your firewall settings and ensure the specified service is online.

LCB_ESOCKSHUTDOWN 

Returned in a callback if the socket connection was gracefully closed, but the library wasn't expecting it.

This may happen if the system is being shut down.

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_ECONNRESET 

Returned in a callback if the socket connection was forcefully reset, Equivalent to the system ECONNRESET.

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_ECANTGETPORT 

Returned in a callback if the library could not allocated a local socket due to TCP local port exhaustion.

This means you have either found a bug in the library or are creating too many TCP connections. Keep in mind that a TCP connection will still occupy a slot in your system socket table even after it has been closed (and will thus appear in a TIME_WAIT state).

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_EFDLIMITREACHED 

Returned if the library could not allocate a new file descriptor for a socket or other resource.

This may be more common on systems (such as Mac OS X ) which have relatively low limits for file descriptors. To raise the file descriptor limit, refer to the ulimit -n command

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_ENETUNREACH 

Returned in callback if the host or subnet containing a node could not be contacted.

This may be a result of a bad routing table or being physically disconnected from the network.

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_ECTL_UNKNOWN 

An unrecognized setting was passed to the lcb_cntl() function

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_ECTL_UNSUPPMODE 

An invalid operation was supplied for a setting to lcb_cntl().

This will happen if you try to write to a read-only setting, or retrieve a value which may only be set. Refer to the documentation for an individual setting to see what modes it supports.

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_ECTL_BADARG 

A malformed argument was passed to lcb_cntl() for the given setting.

See the documentation for the setting to see what arguments it supports and how they are to be supplied.

Note
This error code is returned only if LCB_CNTL_DETAILED_ERRCODES is set
LCB_EMPTY_KEY 

An empty key was passed to an operation.

Most commands do not accept empty keys.

LCB_SSL_ERROR 

A problem with the SSL system was encountered.

Use logging to discover what happened. This error will only be thrown if something internal to the SSL library failed (for example, a bad certificate or bad user input); otherwise a network error will be thrown if an SSL connection was terminated

LCB_SSL_CANTVERIFY 

The certificate the server sent cannot be verified.

This is a possible case of a man-in-the-middle attack, but also of forgetting to supply the path to the CA authority to the library.

LCB_CLIENT_FEATURE_UNAVAILABLE 

An optional client feature was requested, but the current configuration does not allow it to be used.

This might be because it is not available on a particular platform/architecture/operating system/configuration, or it has been disabled at the time the library was built.

LCB_OPTIONS_CONFLICT 

An option was passed to a command which is incompatible with other options.

This may happen if two fields are mutually exclusive

LCB_HTTP_ERROR 

Received in callbacks if an operation failed because of a negative HTTP status code.

LCB_DURABILITY_NO_MUTATION_TOKENS 

Scheduling error received if LCB_CNTL_DURABILITY_MUTATION_TOKENS was enabled, but there is no available mutation token for the key.

LCB_UNKNOWN_MEMCACHED_ERROR 

The server replied with an unrecognized status code.

LCB_MUTATION_LOST 

The server replied that the given mutation has been lost.

LCB_SUBDOC_PATH_ENOENT 

Sub-document path does not exist.

LCB_SUBDOC_PATH_MISMATCH 

Type of element in sub-document path conflicts with type in document.

LCB_SUBDOC_PATH_EINVAL 

Malformed sub-document path.

LCB_SUBDOC_PATH_E2BIG 

Sub-document contains too many components.

LCB_SUBDOC_DOC_E2DEEP 

Existing document contains too many levels of nesting.

LCB_SUBDOC_VALUE_CANTINSERT 

Subdocument operation would invalidate the JSON.

LCB_SUBDOC_DOC_NOTJSON 

Existing document is not valid JSON.

LCB_SUBDOC_NUM_ERANGE 

The existing numeric value is too large.

LCB_SUBDOC_BAD_DELTA 

Delta must be numeric, within the 64 bit signed range, and non-zero.

LCB_SUBDOC_PATH_EEXISTS 

The given path already exists in the document.

LCB_SUBDOC_MULTI_FAILURE 

Could not execute one or more multi lookups or mutations.

LCB_SUBDOC_VALUE_E2DEEP 

Value is too deep to insert.

LCB_EINVAL_MCD 

A badly formatted packet was sent to the server.

Please report this in a bug

LCB_EMPTY_PATH 

Missing subdocument path.

LCB_UNKNOWN_SDCMD 

Unknown subdocument command.

LCB_ENO_COMMANDS 

No commands specified.

LCB_QUERY_ERROR 

Query execution failed.

Inspect raw response object for information

LCB_GENERIC_TMPERR 

Generic temporary error received from server.

LCB_GENERIC_SUBDOCERR 

Generic subdocument error received from server.

LCB_GENERIC_CONSTRAINT_ERR 

Generic constraint error received from server.

LCB_NAMESERVER_ERROR 

Invalid reply received from nameserver.

LCB_NOT_AUTHORIZED 

Not authorized for operation.

LCB_SUBDOC_INVALID_COMBO 

An invalid combination of commands was specified.

LCB_SUBDOC_MULTI_PATH_FAILURE 

Specified key was successfully found, but one or more path operations failed.

LCB_SUBDOC_SUCCESS_DELETED 

The operation completed successfully, but operated on a deleted document.

LCB_SUBDOC_XATTR_INVALID_FLAG_COMBO 

The combination of the subdoc flags for the xattrs is not valid.

LCB_SUBDOC_XATTR_INVALID_KEY_COMBO 

Only a single xattr key may be accessed at the same time.

LCB_SUBDOC_XATTR_UNKNOWN_MACRO 

The server has no knowledge of the requested macro.

LCB_SUBDOC_XATTR_UNKNOWN_VATTR 

The server has no knowledge of the requested virtual xattr.

LCB_SUBDOC_XATTR_CANT_MODIFY_VATTR 

Virtual xattrs cannot be modified.

LCB_SUBDOC_MULTI_PATH_FAILURE_DELETED 

Specified key was found as a deleted document, but one or more path operations failed.

LCB_SUBDOC_INVALID_XATTR_ORDER 

According to the spec all xattr commands should come first, followed by the commands for the document body.

LCB_MAX_ERROR 

The errors below this value reserved for libcouchbase usage.