SDK Release Notes

      Release notes for the Couchbase Kotlin Client.

      Kotlin SDK 1.3 Releases

      We always recommend using the latest version of the SDK — it contains all of the latest security patches and support for new and upcoming features. All patch releases for each dot minor release should be API compatible, and safe to upgrade; any changes to expected behavior are noted in the release notes that follow.

      Version 1.3.1 (5 April 2024)

      This is a regular maintenance release.


      • JVMCBC-1477 Reduced the rate at which messages appear in the server’s http_access.log when invalid credentials are provided resulting in 401 errors. Issues resulting in 403 errors will be handled in a future release.

      • JVMCBC-1499 Disabled DNS SRV caching. The SDK now responds quicker to DNS changes in dynamic environments like Kubernetes.

      Version 1.3.0 (11 March 2024)

      This version adds support for new features in Couchbase Server 7.6: vector search, KV range scan, and sub-document read from replica.

      Additionally, several methods that were previously "volatile" or "uncommitted" are now part of the SDK’s "committed" (stable) public API.


      • KCBC-145: Added support for vector search, a new feature in Couchbase Server 7.6. This API is currently at @Stability.Uncommitted level.

      • JVMCBC-1491: Added support for KV range scan, a new feature in Couchbase Server 7.6. The Collection.scanDocuments() and Collection.scanIds() methods are now part of the SDK’s committed public API.

      • JVMCBC-1493: Added support for Sub-Document read from replica, a new feature in Couchbase Server 7.6. The Collection.lookupInAnyReplica() and Collection.lookupInAllReplicas() methods are now part of the SDK’s committed public API.

      • KCBC-147: Scope.searchIndexes() is now part of the committed public API.

      • KCBC-157: UserManager.changePassword() is now part of the committed public API.

      • KCBC-158: SearchIndexManager is now part of the committed public API.

      • JVMCBC-1487: Upgraded reactor-core from 3.5.8 to 3.6.3.

      • JVMCBC-1488: Upgraded Jackson from 2.16.0 to 2.16.1.

      • JVMCBC-1489: Upgraded Netty from 4.1.101 to 4.1.107.


      • JVMCBC-1480: couchbase2: should do exponential backoff when BestEffortRetryStrategy is used.

      • JVMCBC-1494: If you specify min=1 for a Full-Text Search disjunction query, the SDK now always sends the value to the server. Previously, the SDK assumed 1 was the default value, and omitted the parameter in that case.

      Kotlin SDK 1.2 Releases

      Version 1.2.3 (6 February 2024)

      This is a regular maintenance release.


      • KCBC-146 Collection manager improvements:

        • Added a special max expiry duration, CollectionSpec.NEVER_EXPIRE (equal to -1 seconds), that can be used with Couchbase Server 7.6 and later to indicate documents in a collection should never expire, regardless of the bucket’s max expiry.

        • Updated the API reference documentation to clarify that a collection max expiry of 0.seconds (or null, depending on context) means the collection’s actual max expiry is always the same as the bucket’s max expiry.

      • JVMCBC-1460 couchbase2 now supports compressing data between the SDK and the server.

      • JVMCBC-1464 The metrics-opentelemetry package is now aligned with the same OpenTelemetry version as tracing-opentelemetry.

      • JVMCBC-1468 Cluster.connect now validates that connection strings using the couchbase2 scheme have exactly one host. (Previously, hosts after the first were silently ignored.).

      • JVMCBC-1470 Improved support for Full Text Search in couchbase2 mode.

      • JVMCBC-1472 couchbase2 errors will now include diagnostic information when CNG is running with the --debug flag.


      • JVMCBC-1475 Accessing the terms of a TermFacet result no longer throws NullPointerException if the target field is absent from all documents.

      Version 1.2.2 (5 January 2024)

      This is a regular maintenance release.


      • KCBC-141: Added new QueryMetadata.signatureBytes property. The value is a byte array containing the signature encoded as JSON (QueryMetadata.signature failed if the signature was not a JSON Object). Deprecated QueryMetadata.signature in favor of signatureBytes.


      • JVMCBC-1455: Fixed compatibility with couchbase2:// endpoints by upgrading internal GRPC dependency. All couchbase2 protocol users should upgrade to this release.

      • JVMCBC-1463: Fixed compatibility between couchbase2:// endpoints and the tracing-opentelemetry module.

      Version 1.2.1 (8 December 2023)

      This is a regular maintenance release.


      • JVMCBC-1435, JVMCBC-1436: Upgraded Netty and Jackson dependencies.

      • JVMCBC-1440: Adding DocumentNotLockedException supporting future Couchbase Server versions that will return an error code when unlocking a document that is not locked.


      • JVMCBC-1433: The SDK can now connect to Memcached buckets whose names contain the percent (%) character. (We’d like to take this opportunity to remind everyone that Memcached buckets are deprecated in favor of Ephemeral buckets.)

      • JVMCBC-1437: With Couchbase Server versions that support updating a collection’s max expiry, it’s now possible to clear the expiry by passing Duration.ZERO for the new value.

      • JVMCBC-1441: The SDK now handles an additional error case for IndexNotFoundException.

      • JVMCBC-1442: Fixed a dependency issue with tracing-opentelemetry module.

      Version 1.2.0 (21 November 2023)

      Version 1.2.0 is the first release of the 1.2 series.

      The SDK now supports the new couchbase2 protocol, which is upcoming in future Couchbase Server versions. It can be enabled through using a connection string starting with couchbase2://. Please see Cloud Native Gateway for more information.

      The SDK now directly depends on SLF4J, which may impact some users — see below for details.

      API Impacting

      When upgrading from a previous version of the SDK, please be aware of this behavioral change:

      JVMCBC-1319: As previously announced, the SLF4J API is now a required dependency, and the SDK does all logging through SLF4J. The following client settings for customizing logging behavior are deprecated, and no longer have any effect:

      • logger.disableSlf4J

      • logger.fallbackToConsole

      • logger.consoleLoggerFormatter

      If your project does not already use SLF4J, please follow the announcement link for details and a mini-migration guide.


      • KCBC-132: BucketManager and CollectionManager now know about the history preservation settings added in Couchbase Server 7.2.

        CollectionManager has a new updateCollection method for changing the settings of an existing collection. Note that updating a collection’s maxExpiry setting requires Couchbase Server 7.6.

      • JVMCBC-1402, JVMCBC-1410: Upgraded Netty from 4.1.96 to 4.1.100, and upgraded OpenTelemetry dependency.

      • JVMCBC-1430: Optimization: removed creation of unnecessary metrics labels when default LoggingMeter is used.

      • JVMCBC-1391: The Bucket Manager API is now forward-compatible with future versions of Couchbase Server that might support storage engine types other than "magma" and "couchstore".

      • JVMCBC-1327: Improved support for failover handling in future server versions.


      • KCBC-139: When using BucketManager with Couchbase Server Community Edition, specifying a bucket creation argument not supported by Community Edition now always results in a FeatureNotAvailableException. Previously, this exception was thrown only if the argument differed from the default.

      • JVMCBC-1264: DNS SRV lookups now honor the DNS search path. This enables DNS SRV resolution in Kubernetes environments where the *-srv hostname advertised by the Couchbase Operator is a partial name that must be resolved using a suffix from the DNS search path.

      • JVMCBC-1426: When Couchbase Server is too busy to start a new KV range scan, the SDK now retries instead of throwing a CouchbaseException.

      Kotlin SDK 1.1 Releases

      Version 1.1.11 (4 October 2023)

      This is a regular maintenance release.


      • JCBC-2046: With thanks to community member Marcin Grzejszczak for the contribution, support for Micrometer Observation has been added to all JVM SDKs via the new tracing-micrometer-observation module.

      • JVMCBC-1327: Internal improvements to support upcoming faster failover and config push features.


      • JVMCBC-1364: Fixed decoding of certain niche sub-document errors, so they no longer raise a DecodingFailureException.

      Version 1.1.10 (6 September 2023)


      • JVMCBC-1367: The db.couchbase.operations metric now has (bucket), db.couchbase.scope, db.couchbase.collection and outcome labels (tags). This new feature is at Stability.Volatile, and may change before it is promoted to Stability.Committed in a future release.

      • JVMCBC-1311, JVMCBC-1352: Upgraded dependencies.


      • JVMCBC-1350: lookupInAnyReplica now throws FeatureNotAvailableException if the server does not support the feature.

      • JVMCBC-1351: lookupInAnyReplica no longer hangs when too many operations are specified.

      • JVMCBC-1353: Removed the unrelocated io.opentracing classes that accidentally slipped into version 2.4.9 of the Couchbase core-io library.

      • JVMCBC-1361: When the SDK receives multiple cluster map versions at the same time, it is now more careful about applying only the most recent version. Before this change, there was a brief window where the SDK could apply an obsolete cluster map. If this happened, the SDK would temporarily dispatch requests to incorrect or non-existent nodes. This condition was typically short-lived, and healed the next time the SDK polled for an updated cluster map, or dispatched a KV request to the wrong node.

      • JVMCBC-1368: Fixed a rare java.lang.ArithmeticException: / by zero exception in that could occur during rebalance.

      Version 1.1.9 (2 August 2023)


      • JVMCBC-1339: When KV traffic capture is enabled, each ReadTrafficCapturedEvent now contains a single protocol frame, and the human-readable frame description is more accurate.

      • JVMCBC-1320: The waitUntilReady method is now more aggressive about retrying failed pings. Also, waiting for a desired state of DEGRADED no longer fails when the client is fully connected to the cluster.

      • JVMCBC-1343: Reduced the default value for the io.idleHttpConnectionTimeout client setting to 1 second. The previous default (4.5 seconds) was too close to the 5-second server-side timeout, and could lead to spurious request failures.

      Version 1.1.8 (19 July 2023)


      • JVMCBC-1322: The waitUntilReady() method now logs additional diagnostic information to the com.couchbase.core.WaitUntilReady logging category at DEBUG level.

      Version 1.1.7 (12 June 2023)

      This release refines the sub-document counter methods, and adds a new connection string parameter for disabling TLS certificate verification.


      • KCBC-123: Added new versions of MutateInSpec.incrementAndGet and decrementAndGet without a delta parameter ("increment/decrement" implies the delta is 1). Added a MutateInSpec.addAndGet method that takes a delta. Deprecated the old increment/decrement methods that take a delta, in favor of the new addAndGet method.

      • JVMCBC-1290: Added a new client setting, security.enableCertificateVerification, which defaults to true. This setting allows disabling TLS certificate verification in development environments where configuring the CA certificate to trust is not practical. Setting this to false is equivalent to configuring the environment to use InsecureTrustManager.INSTANCE. For compatibility with other modern Couchbase SDKs, certificate verification can now be disabled using the connection string parameter tls_verify=none. This feature is introduced at stability level Volatile, meaning it may change in a patch release without notice.

      • JVMCBC-1278, JVMCBC-1310, JVMCBC-1313: Dependencies updated.

      Version 1.1.6 (4 May 2023)

      This is a regular maintenance release, with no notable changes apart from depedency version bumps.

      Version 1.1.5 (12 April 2023)

      This is a regular maintenance release.


      • JVMCBC-1223: Adds a RetryReason.AUTHENTICATION_ERROR at Uncommitted API stability level. A custom RetryStrategy can use this new, more granular information to distinguish if a connection problem is down to an authentication issue.

      Bug Fixes

      • KCBC-118: Accessing the result of a sub-document lookupIn exists command now throws an appropriate exception (instead of returning false) in more cases where it’s not possible to determine whether the field exists:

        • If the document is not JSON, DocumentNotJsonException is thrown.

        • If a user without the SystemXattrRead permission attempts to check the existence of a system XATTR, XattrNoAccessException is thrown.

      • JVMCBC-1252: Orphaned "observe" operations will no longer occasionally contain a total_duration_us field equal to 0.

      • JVMCBC-1255: If you were subscribing to the event bus and printing all the events, you may have noticed Event.toString() throwing a NullPointerException if the event context is null. Event.toString() now handles null contexts more gracefully, and no longer throws this exception.

      Version 1.1.4 (8 March 2023)

      This is a regular maintenance release.


      • JVMCBC-1237: Added "network" as an alias for the "io.networkResolution" connection string parameter. For example, the connection string "couchbase://" is now equivalent to "couchbase://". This was done for compatibility with other Couchbase SDKs that use "network" as the name of this parameter.

      Bug Fixes

      • JVMCBC-1232: Cluster.connect() now rejects connection strings that have no addresses (like "couchbase://"). Before this change, it would accept the invalid connection string, and subsequent operations would fail with a misleading error message: "The cluster does not support cluster-level queries".

      Version 1.1.3 (9 February 2023)

      This is a regular maintenance release.


      • JVMCBC-1181: It is now possible to authenticate over secure connections even if the JVM does not support the SASL PLAIN authentication mechanism.

      • JVMCBC-1184: Updated dependencies.

      Bug Fixes

      • JVMCBC-1160: When a sub-document path has a syntax error or is inappropriate for an operation, the SDK now throws PathInvalidException. Prior to this change, it would throw a generic CouchbaseException with the message "Unexpected SubDocument response code".

      Version 1.1.2 (16 January 2023)

      This is a regular maintenance release.


      • JVMCBC-1175: The SDK now includes native libraries for IO and TLS that can enhance performance on aarch_64 architectures like Graviton and Apple Silicon. Previously, native libraries were included only for x86_64 architectures. Native libraries for IO and TLS are enabled by default. If you need to disable native IO, set the ioEnvironment.enableNativeIo client setting to false. To disable native TLS, set the security.enableNativeTls client setting to false.

      Bug Fixes

      • JVMCBC-1161: Fixed a minor issue where cluster.disconnect() could occasionally time out due to a race condition.

      • JVMCBC-1176: Setting security.enableNativeTls to false now prevents the SDK from even attempting to load the native TLS library. (Prior to this change, the SDK would load the library and just not use it.) In addition to saving a bit of memory, this prevents the JVM from segfaulting on Alpine Linux where glibc is not available.

      • JVMCBC-1174: Fixed a regression that prevented native TLS from being used regardless of whether the security.enableNativeTls client setting was set to true.

      Version 1.1.1 (7 December 2022)


      • JVMCBC-1163: Dependencies have been updated.

      • JVMCBC-1156: The traffic tracing functionality has been enhanced to perform Wireshark-style dissection of portions of the KV protocol.

      • JCBC-2021: Diagnostics for an endpoint now include the state of the endpoint’s circuit breaker.

      Bug Fixes

      • KCBC-107: The logging configuration DSL property enableDiagnosticContext is now mutable.

      • JVMCBC-1157: The SDK no longer rejects a PersistTo requirement in a bucket using the Magma storage engine. Before this change, the SDK would refuse the request because it misidentified Magma buckets as ephemeral (unable to persist documents).

      • JVMCBC-1167: If you call CancellationErrorContext.getWaitUntilReadyContext() on an error context that didn’t come from a "wait until ready" request, the method is now guaranteed to return null instead of sometimes throwing a ClassCastException.

      • JVMCBC-1178: Fixed a memory leak in ManagerMessageHandler.

      Version 1.1.0 (24 October 2022)


      • JVMCBC-1102: Added support for serverless execution environments including AWS Lambda.

      • KCBC-101: Added an experimental JSON serializer backed by kotlinx.serialization. See this sample code for usage and caveats.

      • KCBC-102: Added support for configuration profiles, which allow you to quickly configure an environment for common use-cases. In particular, this makes it easy to apply timeouts appropriate for WAN (Internet) development, such as developing against a remote Couchbase Capella instance. Example usage:

        val cluster = Cluster.connect(
            connectionString, username, password
        ) {
      • KCBC-105, JVMCBC-1144: If your Couchbase Server cluster’s root certificate is signed by a well-known certificate authority whose certificate is included in the JVM’s trust store, it’s no longer necessary to configure the certificate in the securityConfig settings.

      • KCBC-104: Changed AuthenticationFailureException error message to indicate that bucket hibernation is now a potential cause. Bucket hibernation is a feature coming in a future Couchbase release.

      • JVMCBC-1154: Bumped dependencies.

      Bug Fixes

      • JVMCBC-1141: Provide required OpenTelemetry span attributes.

      • JVMCBC-1155: Make sure targeted round-robin request keeps retrying if no config is available.

      Kotlin SDK 1.0 Releases

      Version 1.0.4 (9 September 2022)

      This maintenance release adds more cluster management APIs, and updates dependency versions.


      • KCBC-94: UserManager has a new changePassword function that lets you change the password of the currently authenticated user.

      • KCBC-99: Bucket has a new collections property of type CollectionManager. You can use the collection manager to create and delete scopes and collections. (Requires Couchbase Server 7.0 or later.)

      • KCBC-100: Added two new global config properties to help diagnose leaked Cluster instances. Cluster.maxAllowedInstances is the number of connected Cluster instances that may exist at the same time. Calling Cluster.connect after this limit is reached will either fail or log a warning, depending on the value of the new Cluster.failIfInstanceLimitReached property. The default values log a warning if more than 1 Cluster is connected at a time.

      • JVMCBC-1134: Updated MemcachedProtocol::decodeStatus to be inlineable.

      • JVMCBC-1135: Moved Core#reconfiguration off IO threads.

      • JVMCBC-1143: Failed telemetry spans will now record their exception and error status.

      • JVMCBC-1145: Updated maintenance dependencies.

      Version 1.0.3 (2 August 2022)

      Maintenance release.


      • JVMCBC-1116: Dependency versions have been increased.

      Bug Fixes

      • JVMCBC-1119: The num (kv) nodesExt to equal number of nodes check can lead to otherwise healthy clusters being flagged as not ready. The check has been removed, and now bucket.waitUntilReady will not time out on these edge cases.

      • JVMCBC-1120: ClusterConfig#allNodeAddresses now takes global config into account — avoiding the triggering of some unnecessary reconfigurations.

      • JVMCBC-1112: Deprecated Reactor Processors have been replaced.

      • JVMCBC-1115: The SDK now allows for configurations with only TLS ports.

      Version 1.0.2 (6 July 2022)

      Maintenance release.

      Bug Fixes

      • JVMCBC-1103: To reduce overhead, the MAX_PARALLEL_FETCH value in KeyValueBucketRefresher has been updated to only fetch one config per poll interval.

      • JVMCBC-1104: Fixed issue where the global refresher did not honor the config poll interval.

      Version 1.0.1 (8 June 2022)

      Maintenance release.


      • KCBC-79: JacksonJsonSerializer now accepts the jackson ObjectMapper which for example makes it easier to use out of the box with Spring Boot.

      • JVMCBC-1093: Previously, when a DNS SRV lookup failure occurred, the SDK logged this as a WARNING along with a stack trace. The lookup failure is typically harmless, so the log message has now been downgraded to INFO level, without a stack trace.

      • JVMCBC-1088: Updated Netty to version 4.1.77.Final.

      Version 1.0.0 (3 May 2022)

      Initial GA release.