The standardized error codes returned by the Couchbase PHP SDK, from cloud connection to sub-document.
All exceptions derive from a common base Couchbase exception. Exceptions (errors) are broken into different classifications:
Shared Exceptions — exceptions or errors thrown or returned by any service.
Specific Exceptions — exceptions or errors thrown by a service and specific to the service that threw or returned them.
Internal Exceptions — exceptions intended to be handled internally by the SDK and not exposed to the application.
The base exception,
CouchbaseException, has two properties — an
ErrorContext and an optional Cause.
ErrorContext provides extensive debugging information in JSON format.
Below are the exceptions, categorised by service.
Shared Error Definitions
ID Range: 1-99
# 1 Timeout
Raised when a request cannot be completed until the user-defined timeout fires.
Note, this is a base class for #13 and #14 (Ambiguous and Unambiguous).
# 2 RequestCanceled
Raised when a request is cancelled and cannot be resolved in a non-ambiguous way. Most likely the request is in-flight on the socket and the socket gets closed.
# 3 InvalidArgument
Raised when it is unambiguously determined that the error was caused because of invalid arguments from the user. Usually only thrown directly when doing request arg validation on KV and sub-doc. Also commonly used as a parent class for many service-specific exceptions (see below).
# 4 ServiceNotAvailable
Raised when it can be determined from the config unambiguously that a given service is not available. I.e. no query node in the config, or a memcached bucket is accessed and views or queries should be performed.
# 5 InternalServerFailure
Raised when: * Query: Error range 5xxx. * Analytics: Error range 25xxx. * KV: error code ERR_INTERNAL (0x84). * Search: HTTP 500.
# 6 AuthenticationFailure
* Query: Error range 10xxx.
* Analytics: Error range 20xxx.
* View: HTTP status 401.
* KV: error code
* Search: HTTP status 401, 403.
# 7 TemporaryFailure
* Analytics: Errors: 23000, 23003.
* KV: Error code
# 9 CasMismatch
ERR_EXISTS (0x02) when replace or remove with CAS.
* Query: code 12009.
# 11 CollectionNotFound
Raised when a request is made but the current collection (including scope) is not found.
# 13 AmbiguousTimeout
Raised when a timeout occurs and we aren’t sure if the underlying operation has completed. This normally occurs because we sent the request to the server successfully, but timed out waiting for the response. Note that idempotent operations should never return this, as they do not have ambiguity.
# 14 UnambiguousTimeout
Raised when a timeout occurs and we are confident that the operation could not have succeeded. This normally would occur because we received confident failures from the server, or never managed to successfully dispatch the operation.
# 17 IndexNotFound
Raised when: * Query: Codes 12004, 12016. Codes 5000 AND message contains index .+ not found. * Analytics: rised when 24047 raised. * Search: Http status code 400 AND text contains "index not found".
# 18 IndexExists
# 19 EncodingFailure
Raised when encoding of a user object failed while trying to write it to the cluster.
KeyValue Error Definitions
ID Range 100 - 199
# 101 DocumentNotFound
Raised when the document requested was not found on the server — KV Code
# 102 DocumentUnretrievable
Raised when in
getAllReplicas returns an empty stream because all the individual errors are dropped (i.e. all returned a
# 104 ValueTooLarge
Raised when the value that was sent was too large to store (typically > 20MB); KV Code
# 105 DocumentExists
Raised when an operation which relies on the document not existing fails because the document existed; KV Code
# 107 DurabilityLevelNotAvailable
Raised when the specified durability level is invalid; KV Code
# 108 DurabilityImpossible
Raised when the specified durability requirements are not currently possible (for example, there are an insufficient number of replicas online); KV Code
# 109 DurabilityAmbiguous
Raised when A sync-write has not completed in the specified time and has an ambiguous result - it may have succeeded or failed, but the final result is not yet known. A SEQNO OBSERVE operation is performed and the vbucket UUID changes during polling. KV Code 0xa3
# 110 DurableWriteInProgress
Raised when A durable write is attempted against a key which already has a pending durable write. KV Code 0xa2
# 111 DurableWriteReCommitInProgress
Raised when The server is currently working to synchronize all replicas for previously performed durable operations (typically occurs after a rebalance). KV Code 0xa4
# 113 PathNotFound
Raised when the path provided for a sub-document operation was not found; KV Code
# 114 PathMismatch
The path provided for a sub-document operation did not match the actual structure of the document; KV Code
# 115 PathInvalid
Raised when the path provided for a sub-document operation was not syntactically correct; KV Code
# 116 PathTooBig
Raised when the path provided for a sub-document operation is too long, or contains too many independent components; KV Code
# 118 ValueTooDeep
Raised when the value provided, if inserted into the document, would cause the document to become too deep for the server to accept; KV Code
# 119 ValueInvalid
Raised when the value provided for a sub-document operation would invalidate the JSON structure of the document if inserted as requested; KV Code
# 120 DocumentNotJson
Raised when a Sub-Document operation is performed on a non-JSON document; KV Code
# 121 NumberTooBig
Raised when the existing number is outside the valid range for arithmetic operations; KV Code
# 122 DeltaInvalid
Raised when the delta value specified for an operation is too large; KV Code
# 123 PathExists
Raised when a sub-document operation which relies on a path not existing encountered a path which exists; KV Code
# 124 XattrUnknownMacro
Raised when a macro was used which the server did not understand; KV Code:
# 126 XattrInvalidKeyCombo
Raised when a Sub-Document operation attempts to access multiple xattrs in one operation; KV Code:
# 127 XattrUnknownVirtualAttribute
Raised when a sub-document operation attempts to access a virtual attribute; KV Code:
# 128 XattrCannotModifyVirtualAttribute
Raised when a Sub-Document operation attempts to modify a virtual attribute; KV Code:
Query Error Definitions
ID Range 200 - 299
# 201 PlanningFailure
Query: Raised when code range 4xxx other than those explicitly covered.
# 202 IndexFailure
# 203 PreparedStatementFailure
Query: Raised when codes 4040, 4050, 4060, 4070, 4080, 4090.
Analytics Error Definitions
ID Range 300 - 399
# 301 CompilationFailure
Raised when error range 24xxx (excluded are specific codes in the errors below).
# 302 JobQueueFull
Raised when error code 23007.
# 303 DatasetNotFound
Raised when error codes 24044, 24045, 24025.
# 304 DataverseNotFound
Raised when error code 24034.
# 305 DatasetExists
Raised when 24040.
# 306 DataverseExists
Raised when 24039.
# 307 LinkNotFound
Raised when 24006.
Search Error Definition
ID Range 400 - 499
There are no specific errors for Search; see the Shared Error Definitions section for errors that apply to Search.
View Error Definitions
Management API Error Definitions
ID Range 600 - 699
Field-Level Encryption Error Definitions
ID Range 700 - 799
Note, in SDK 3.0, Field Level Encryption is only available as a Developer Preview with the Java SDK.
# 700 CryptoException
Generic cryptography failure. Inherits from CouchbaseException (=== # 0). Parent Type for all other Field-Level Encryption errors.
# 701 EncryptionFailure
CryptoManager.encrypt() when encryption fails for any reason.
Should have one of the other Field-Level Encryption errors as a cause.
# 702 DecryptionFailure
CryptoManager.decrypt() when decryption fails for any reason.
Should have one of the other Field-Level Encryption errors as a cause.
# 704 InvalidCryptoKey
Raised by an encrypter or decrypter when the key does not meet expectations (for example, if the key is the wrong size).
# 705 DecrypterNotFound
Raised when a message cannot be decrypted because there is no decrypter registered for the algorithm.
# 706 EncrypterNotFound
Raised when a message cannot be encrypted because there is no encrypter registered under the requested alias.
Connecting to Cloud
Although the SDK and client application should be located in the same LAN-like environment (or cloud availability zone), and this is the only network configuration supported, we recognise that this set-up may not be possible during development. In particular, you may be developing against Couchbase Capella from a laptop in a small or home office, where DNS-SRV may cause problems.
In order for your application to connect to your cloud, Capella creates a special kind of DNS record, called a Service record, or DNS-SRV record. DNS SRV records are widely supported and used frequently in systems like XMPP, and Kubernetes services. Occasionally, some DNS providers can run into issues with large DNS SRV records. This can manifest as a host not found issue. The actual problem is (a typically older) DNS server that cannot handle large responses which converts the error to host not found. This has frequently been observed when working from home with a service provider router that embeds a caching DNS Server.
Below is a list of log messages that you may see if you hit DNS SRV issues. These examples have been created in the circumstance that the SRV record is too long for the DNS provider to handle, and are included here so that they are findable by search, and you can then go to our cloud connection troubleshooting page.
[cb,EROR] (connection L:503 I:3705255243) <8676842d-4e8b-4c5b-a44f-e0886f8c0bc1.dp.cloud.couchbase.com:11207> (SOCK=762eb846eaa3268f) Couldn't look up 8676842d-4e8b-4c5b-a44f-e0886f8c0bc1.dp.cloud.couchbase.com (nodename nor servname provided, or not known) [EAI=8]
[cb,EROR] (connection L:164 I:3705255243) <8676842d-4e8b-4c5b-a44f-e0886f8c0bc1.dp.cloud.couchbase.com:11207> (SOCK=762eb846eaa3268f) Failed to establish connection: LCB_ERR_UNKNOWN_HOST (1049), os errno=0
[cb,EROR] (cccp L:171 I:3705255243) <NOHOST:NOPORT> (CTX=0x0,) Could not get configuration: LCB_ERR_UNKNOWN_HOST (1049)
Our practical look at error handling with the SDK.
Discussion document on handling exceptions.
Further reference material in the API Guide.