Couchbase Java SDK Release Notes and Archives

Release notes, installation instructions, and download archive for the Couchbase Java Client.

These pages cover the 3.0 versions of the Couchbase Java SDK. For release notes, download links, and installation methods for 2.7 and earlier releases of the Couchbase Java Client, which will not work with Distributed Transactions, please see the 2.x Java Release Notes & Download Archive.

Transactions is available as a separate library for the Java SDK. Please see the Transaction Release Notes page.


At least Java 8 is required for current releases; see the Compatibility section for details. We recommend running the latest LTS version (i.e. at the time of writing JDK 11) with the highest patch version available. Java 11 has various enhancements like lambda local variable type inference, profiling tools, and updated security features.


Version 3.0.3 (7 April 2020)

Version 3.0.3 is the fourth release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

The supported and tested dependencies for this release are:

  • com.couchbase.client:java-client:3.0.3

  • com.couchbase.client:core-io:2.0.4

  • io.projectreactor:reactor-core:3.3.3.RELEASE

  • org.reactivestreams:reactive-streams:1.0.2


  • JCBC-1603, JCBC-1606: Exposed API to set the collections TTL. CreateCollection CollectionSpec now includes MaxTTL.

  • JCBC-1617: Attempting to work with the collection manager on clusters where collections are not available (or enabled as a DP) will now result in a FeatureNotAvailable failure.

  • JVMCBC-830: Added more convenient overloads for SecurityConfig and CertAuth. These overloads initialize both the SecurityConfig and the CertificateAuthenticator directly from a KeyStore or TrustStore.

  • JVMCBC-831: Improves timeout for waitUntilReady — the waitUntilReady helper should now throw a proper timeout exception.

  • JVMCBC-832: Added support for multiple ports per hostname in the connection string — without having to use the explicit SeedNode set overload.

  • JVMCBC-835: Using "localhost:8091" as a connection string would set the kv bootstrap port to 8091, which is not desired behavior. To prevent this from happening again, the code now checks for this condition, fails fast, and also provides guidance on what the connection string should look like instead.

  • JVMCBC-836: Enabled Unordered Execution by Default.

  • JVMCBC-837: Updates OpenTelemetry to 0.3 (beta).

Bug Fixes

  • JCBC-1618: Named fields in SearchRows results are now deserialized.

  • JVMCBC-834: 'CollectionNotFoundException' now triggers a retry, and if no collection refresh is currently in progress it will proactively trigger a new one. Now Docs created under custom collection should no longer raise an exception when a collection has been created in the meantime, but the collection is not found as no refresh is in progress.

  • JVMCBC-826: A NullPointerException was occuring when LDAP is enabled. The code now explicitly fails the connection with a descriptive error message instructing the user what to do next (either use TLS which is preferred) or enable PLAIN on the password authenticator (insecure).

  • JVMCBC-827: Search query results row_hit typo resulted in 0 being returned for total rows. This has now been fixed.

  • JVMCBC-828: Omit internal config request in orphan reporting.

  • JVMCBC-839: Bootstrap will now correctly use the mapped port if alternate addr is present.

Version 3.0.2 (3 March 2020)

Version 3.0.2 is the third release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

The supported and tested dependencies for this release are:

  • com.couchbase.client:java-client:3.0.2

  • com.couchbase.client:core-io:2.0.3

  • io.projectreactor:reactor-core:3.3.1.RELEASE

  • org.reactivestreams:reactive-streams:1.0.2


  • JCBC-1588: Give TypeRef overload of JsonSerializer a default "unsupported" impl, making it easier for applications to implement custom JsonSerializers.

  • JVMCBC-813: Improved error message for bucket is missing.

  • JVMCBC-815: Check if key exceeds size limits.

  • JVMCBC-818: Trimmed netty stack in connect failures for more readable output.

  • JVMCBC-819: Distinguished bucket not found in select bucket failures.

  • JVMCBC-823: Added a global component to the core id.

  • JVMCBC-825: Support added for new VATTR HELLO flag.

Bug Fixes

  • JCBC-1587: Exists no longer returns wrong value if executed right after remove.

  • JCBC-1600: Using expiry together with document flags on a Sub-Document mutateIn no longer causes an incorrect flags field to be sent.

  • JCBC-1604: Properly clear cache when repreparing/retrying query.

  • JVMCBC-824: Native Netty transports not included, resulting in fallback to default implementation. Only affected 2.0.2 core release.

Version 3.0.1 (5 February 2020)

Version 3.0.1 is the second release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

The supported and tested dependencies for this release are:

  • com.couchbase.client:java-client:3.0.1

  • com.couchbase.client:core-io:2.0.2

  • io.projectreactor:reactor-core:3.3.1.RELEASE

  • org.reactivestreams:reactive-streams:1.0.2


  • JCBC-1578: Added support for Java Object Serialization as a custom Transcoder.

  • JVMCBC-808: The internal packaged netty dependency has been reduced to the minimum amount of artifacts needed, trimming the resulting jar size a little.

Bug Fixes

  • JCBC-1574: JsonObject/Array.put(String,Object) now supports writing generic Maps and Lists.

  • JCBC-1580: The code for get projections had an import for unbundled jackson which prevented it from working in an environment where no unbundled jackson is on the classpath. This no longer occurs.

  • JCBC-1582: The client context ID is now propagated into the PREPARE query if needed.

  • JVMCBC-806: TLS: remote hostname and port are passed down to the SSL engine, making sure that hostname validation works as expected.

  • JCBC-1575: Bucket Management: BucketSettings load does now recognize numReplicas properly.

Known Issues

  • JVMCBC-805: When bootstrapping against a non-KV node the KV socket is not cleaned up properly. As a workaround (and as we recommend in general), please only bootstrap against nodes which have the KV service enabled. Or maintain a list of KV nodes in DNS SRV.

Version 3.0.0 (10 January 2020)

This is the first GA release of the third generation Java SDK.

The supported and tested dependencies for this release are:

  • com.couchbase.client:java-client:3.0.0

  • com.couchbase.client:core-io:2.0.0

  • io.projectreactor:reactor-core:3.3.1.RELEASE

  • org.reactivestreams:reactive-streams:1.0.2


The following list describes the API changes between 3.0.0 beta.2 and 3.0.0 GA.

  • JCBC-1563: Added the reactive API to the view index manager.

  • JVMCBC-776: Added support for server-side KV tracing statistics.

  • JCBC-1522: All data commands have been instrumented to be included in RTO (Response Time Observability).

  • JCBC-1566, JCBC-1568: The Search API has been slightly improved to align with the SDK RFC.

  • JCBC-1599: Bucket, Scope and Collection instances are now cached so repeated open attempts produce less garbage and happen quicker.

  • JVMCBC-785, JVMCBC-786, JVMCBC-675: View, Search, Analytics, and Query retryable error codes are now retried as part of the configured retry strategy.

  • JCBC-1561, JCBC-1562: Added Option overloads to collection and search index managers.

  • JVMCBC-787, JVMCBC-788: View requests and KV collection requests are now short-circuited against unsupported clusters.

  • JCBC-1552: Added support for Java 9 automatic module names.

  • JCBC-1554: JsonArry and JsonObject now support toArray in addition to toString.

  • JCBC-1545: The ping command has been reintroduced to the cluster and bucket level APIs.

  • JCBC-1518: An internal server error from the KV engine is now properly mapped to the exception equivalent.

  • JVMCBC-779: It is now possible to customize the event loop thread count instead of having to provide a new event loop itself.

  • JVMCBC-767: A new ConfigIdleRedialTimeout has been introduced which recycles idle HTTP streaming connections.

  • JVMCBC-782: The orphan response reporter (as part of RTO) has been ported to SDK 3 from SDK 2 and is now enabled by default.

  • JVMCBC-784: Idle HTTP connections are now closed after 30 seconds.

  • JVMCBC-773: SASL PLAIN is now not negotiated by default on non-TLS connections to prevent downgrade attacks out of the box.

  • JVMCBC-795: Requests are now failed fast if it can be determined that the service is not available on the cluster.

  • JVMCBC-790: The concept of backpressure has been re-introduced but in slightly different form.

  • JVMCBC-: The circuit breaker now has a customizable completion callback.

Bug Fixes

The following list describes the API changes between 3.0.0 beta.2 and 3.0.0 GA.

  • JCBC-1550: The owned environment in the Cluster is now properly shutdown on disconnect.

  • JCBC-1517, JCBC-1566: All reactive APIs are now deferred and will not execute I/O side effects when not subscribed to.

  • JCBC-1539: A bug has been fixed where the IoConfig.networkResolution could not be set through a system property.

  • JVMCBC-793: Various fixes have been made around DNS SRV bootstrapping that make it more robust, including fixing a bug that prevented it from working properly.

  • JCBC-1524: The projections on get have been refactored, the test suite expanded, and a couple of issues fixed along the way.

  • JCBC-1531: The QueryIndexManager now only returns GSI indexes.

  • JVMCBC-802: A bug has been fixed where a non-existing view in an existing design document would not cause an exception.

  • JCBC-1565: Views now use the right default View timeout instead of the Analytics one.

  • JVMCBC-789: Performing operations while initially loading the collection map is now handled gracefully.

Known Issues

  • JVMCBC-805: When bootstrapping against a non-KV node the KV socket is not cleaned up properly. As a workaround (an we recommend in general) please only bootstrap against nodes which have the KV service enabled.

API Changes

The following list describes the API changes between 3.0.0 beta.2 and 3.0.0 GA. Since SDK 3 is a complete rewrite over SDK 2, the individual changes between them are not listed here. Please refer to the migration guide for this.

  • JCBC-1533, JCBC-1534, JCBC-1535, JCBC-1541, JCBC-1542: Exceptions have been consolidated, renamed, and overall aligned with the latest RFC.

  • JCBC-1536: SeedNodes have been moved out of the ClusterOptions into a Cluster#connect() overload.

  • JCBC-1540: MajorityAndPersistOnMaster has been renamed to MajorityAndPersistToActive on the durability enum.

  • JCBC-1545: The diagnostics API has been reworked on all levels.

  • JCBC-1551: The empty constructors are gone from JsonObject and JsonArray since they duplicate create.


Numerous Alpha and Beta releases were made in the run-up to the 3.0 release, and although unsupported, the release notes and download links are retained for archive purposes here.