Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Errors & Exceptions Reference

    +
    The standardized error codes returned by the Couchbase Scala 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. The ErrorContext provides extensive debugging information in JSON format.

    Below are the exceptions, categorised by service.

    Shared Error Definitions

    Timeout

    Raised when a request cannot be completed until the user-defined timeout fires.

    Note, this is a base class for AmbiguousTimeout and UnambiguousTimeout.

    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.

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

    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 n1ql queries should be performed.

    InternalServerFailure

    Raised when:

    • Query: Error range 5xxx.

    • Analytics: Error range 25xxx.

    • KV: error code ERR_INTERNAL (0x84).

    • Search: HTTP 500.

    AuthenticationFailure

    Raised when:

    • Query: Error range 10xxx.

    • Analytics: Error range 20xxx.

    • View: HTTP status 401.

    • KV: error code ERR_ACCESS (0x24), ERR_AUTH_ERROR (0x20), AUTH_STALE (0x1f).

    • Search: HTTP status 401, 403.

    TemporaryFailure

    Raised when:

    • Analytics: Errors: 23000, 23003.

    • KV: Error code ERR_TMPFAIL (0x86), ERR_BUSY (0x85) ERR_OUT_OF_MEMORY (0x82), ERR_NOT_INITIALIZED (0x25).

    ParsingFailure

    Raised when:

    CasMismatch

    Raised when:

    • KV: ERR_EXISTS (0x02) when replace or remove with CAS.

    • Query: code 12009.

    BucketNotFound

    Raised when a request is made but the current bucket is not found.

    CollectionNotFound

    Raised when a request is made but the current collection (including scope) is not found.

    UnsupportedOperation

    Raised when:

    • KV: 0x81 (unknown command), 0x83 (not supported).

    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.

    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.

    FeatureNotAvailable

    Raised when a feature which is not available was used.

    ScopeNotFound

    Raised when a management API attempts to target a scope which does not exist.

    IndexNotFound

    Raised when:

    • Query:

    • Analytics: rised when 24047 raised.

    • Search: Http status code 400 AND text contains "index not found".

    IndexExists

    • Query: Raised when

      • Code 5000 AND message contains Index .+ already exist

      • Code 4300 AND message contains index .+ already exist

    • Analytics: Raised when 24048 raised.

    EncodingFailure

    Raised when encoding of a user object failed while trying to write it to the cluster.

    DecodingFailure

    Raised when decoding of the data into the user object failed.

    KeyValue Error Definitions

    DocumentNotFound

    Raised when:

    • KV: Code 0x01. The document requested was not found on the server.

    DocumentUnretrievable

    Raised when in getAnyReplica, the getAllReplicas returns an empty stream because all the individual errors are dropped (i.e. all returned a DocumentNotFound).

    DocumentLocked

    Raised when:

    • KV: Code 0x09. The document requested was locked.

    ValueTooLarge

    Raised when:

    • KV: Code 0x03. The value that was sent was too large to store (typically > 20MB).

    DocumentExists

    Raised when:

    • KV: Code 0x02. An operation which relies on the document not existing fails because the document existed.

    DurabilityLevelNotAvailable

    Raised when:

    • KV: Code 0xa0. The specified durability level is invalid.

    DurabilityImpossible

    Raised when:

    • KV: Code 0xa1. The specified durability requirements are not currently possible (for example, there are an insufficient number of replicas online).

    DurabilityAmbiguous

    Raised when:

    • KV: Code 0xa3.

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

    DurableWriteInProgress

    Raised when:

    • KV: Code 0xa2. A durable write is attempted against a key which already has a pending durable write.

    DurableWriteReCommitInProgress

    Raised when:

    • KV: Code 0xa4. The server is currently working to synchronize all replicas for previously performed durable operations (typically occurs after a rebalance).

    PathNotFound

    Raised when:

    • KV: Code 0xc0. The path provided for a sub-document operation was not found.

    PathMismatch

    Raised when:

    • KV: Code 0xc1. The path provided for a sub-document operation did not match the actual structure of the document.

    PathInvalid

    Raised when:

    • KV: Code 0xc2. The path provided for a sub-document operation was not syntactically correct.

    PathTooBig

    Raised when:

    • KV: Code 0xc3. The path provided for a sub-document operation is too long, or contains too many independent components.

    PathTooDeep

    Raised when:

    • KV: Code 0xc4. The document contains too many levels to parse.

    ValueTooDeep

    Raised when:

    • KV: Code 0xca. The value provided, if inserted into the document, would cause the document to become too deep for the server to accept.

    ValueInvalid

    Raised when:

    • KV: Code 0xc5. The value provided for a sub-document operation would invalidate the JSON structure of the document if inserted as requested.

    DocumentNotJson

    Raised when:

    • KV: Code 0xc6. A Sub-Document operation is performed on a non-JSON document.

    NumberTooBig

    Raised when:

    • KV: Code 0xc7. The existing number is outside the valid range for arithmetic operations.

    DeltaInvalid

    Raised when:

    • KV: Code 0xc8. The delta value specified for an operation is too large.

    PathExists

    Raised when:

    • KV: Code 0xc9. A sub-document operation which relies on a path not existing encountered a path which exists.

    XattrUnknownMacro

    Raised when:

    • KV: Code 0xd0. A macro was used which the server did not understand.

    XattrInvalidKeyCombo

    Raised when:

    • KV: Code 0xcf. A Sub-Document operation attempts to access multiple xattrs in one operation.

    XattrUnknownVirtualAttribute

    Raised when:

    • KV: Code 0xd1. A sub-document operation attempts to access a virtual attribute.

    XattrCannotModifyVirtualAttribute

    Raised when:

    • KV: Code 0xd2. A Sub-Document operation attempts to modify a virtual attribute.

    XattrNoAccess

    Raised when:

    • KV: Code 0x24. The user does not have permission to access the attribute. Occurs when the user attempts to read or write a system attribute (name starts with underscore) but does not have the SystemXattrRead / SystemXattrWrite permission.

    Query Error Definitions

    PlanningFailure

    • Query: Raised when code range 4xxx other than those explicitly covered.

    IndexFailure

    • Query: Raised when code range 12xxx and 14xxx raised (other than 12004 and 12016).

    PreparedStatementFailure

    Analytics Error Definitions

    CompilationFailure

    Raised when error range 24xxx (excluded are specific codes in the errors below).

    JobQueueFull

    Raised when error code 23007.

    DatasetNotFound

    Raised when error codes 24044, 24045, 24025.

    DataverseNotFound

    Raised when error code 24034.

    DatasetExists

    Raised when 24040.

    DataverseExists

    Raised when 24039.

    LinkNotFound

    Raised when 24006.

    Search Error Definition

    There are no specific errors for Search; see the Shared Error Definitions section for errors that apply to Search.

    View Error Definitions

    ViewNotFound

    Raised when Http status code 404 — reason or error contains “not_found”.

    DesignDocumentNotFound

    Raised on the Management APIs only when:

    • Getting a design document;

    • Dropping a design document;

    • And the server returns 404.

    Management API Error Definitions

    CollectionExists

    Raised from the collection management API.

    ScopeExists

    Raised from the collection management API.

    UserNotFound

    Raised from the user management API.

    GroupNotFound

    Raised from the user management API.

    BucketExists

    Raised from the bucket management API.

    UserExists

    Raised from the user management API.

    BucketNotFlushable

    Raised from the bucket management API.

    Field-Level Encryption Error Definitions

    Note, in SDK 3.0, Field Level Encryption is only available as a Developer Preview with the Java SDK.

    CryptoException

    Generic cryptography failure. Inherits from CouchbaseException. Parent Type for all other Field-Level Encryption errors.

    EncryptionFailure

    Raised by CryptoManager.encrypt() when encryption fails for any reason. Should have one of the other Field-Level Encryption errors as a cause.

    DecryptionFailure

    Raised by CryptoManager.decrypt() when decryption fails for any reason. Should have one of the other Field-Level Encryption errors as a cause.

    CryptoKeyNotFound

    Raised when a crypto operation fails because a required key is missing.

    InvalidCryptoKey

    Raised by an encrypter or decrypter when the key does not meet expectations (for example, if the key is the wrong size).

    DecrypterNotFound

    Raised when a message cannot be decrypted because there is no decrypter registered for the algorithm.

    EncrypterNotFound

    Raised when a message cannot be encrypted because there is no encrypter registered under the requested alias.

    InvalidCiphertext

    Raised when decryption fails due to malformed input, integrity check failure, etc.

    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.

    

    

    

    

    

    

    Further Reading