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.7 (4 August 2020)

    Version 3.0.7 is the eighth 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.7

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

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

    • org.reactivestreams:reactive-streams:1.0.3

    API Affecting

    • JCBC-1681: Removed cas from IncrementOptions and DecrementOptions. CAS is not supported by the underlying protocol and should not have been exposed in these options.

    • JCBC-1625: Deprecated maxTTL on BucketSettings in favor of maxExpiry.

    Bug Fixes

    • JCBC-1647: Deprecated EjectionPolicy in favor of EvictionPolicyType. And added the "noEviction" and "nruEviction" policies used by ephemeral buckets. This fixed a but where the BucketManager didn’t recognize ephemeral bucket ejection values. Users can now set a non-default ejection policy when creating an ephemeral bucket.

    • JCBC-1668: Fixes an NPE when toString or fieldsAs is called when no fields are present in the result. In this case just null should now be returned, instead of a NPE deep down in the Jackson serializer stack.

    • JVMCBC-870: A bug in the chunk response parser prohibited responses meant that View reduce responses were never completed, and as a result timed out on the user side. The completion of view results with reduce enabled has now been fixed.


    • JCBC-1661, JCBC-1665: Building on the expiry improvements in the previous release, this adds a new expiryTime() method that returns expiry as an Instant, which better expresses the concept than the Duration returned by expiry(). The latter will be deprecated in a future release. Similarly, everywhere a Duration-based expiry could be provided previously, an overload has been added to take an Instant-based expiry.

    • JCBC-1666: Made bucket.scope("_default").collection("_default") behave just like bucket.defaultCollection(). AsyncScope.collection() now no longer refreshes collection map for default collection.

    • JCBC-1670: Added WaitUntilReadyOptions.serviceTypes() overload that accepts varargs.

    • JVMCBC-867: Performance improvement: do not grab ByteBuf slice when extracting server response time.

    • JVMCBC-869: Maintenance dependency bump: Netty → 4.1.51, Jackson → 2.11.1, Reactor → 3.3.7, OpenTelemetry → 0.6.0.

    Version 3.0.6 (14 July 2020)

    Version 3.0.6 is the seventh 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.6

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

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

    • org.reactivestreams:reactive-streams:1.0.3


    • JCBC-1645: Specifying document expiries has been made significantly easier. Expiries are supplied as a Duration. The new behaviour is that if that duration is less than 50 years, then it will be interpreted as being a relative timestamp from the current time. E.g. Duration.ofDays(35) will expire in 35 days time. (Previously, a Duration longer than 30 days would be interpreted as being an epoch time. Unless this epoch time occurred in the future then it would expire immediately. In order to preserve compatibility for users that worked around this behaviour, any Duration longer than 50 years will continue to be interpreted as an epoch time.)

    • JCBC-1632: Bootstrapping is now fully pipelined for performance, building on the improvements in the previous release.

    • JVMCBC-865: Changed the default idle timeout to 4.5s for http connections, to support performance improvements in query service.

    Bug Fixes

    • JCBC-1662: MutateInMacro for CRC32 is fixed.

    • JCBC-1664: viewQuery with ViewOptions.viewOptions().keys(keys) was returning a bad_request error. This is now fixed.

    • JVMCBC-849: Redundant global loading exceptions no longer propagated — now logged at debug level.

    • JVMCBC-856: A just-opened connection in pool no longer gets cleaned up prematurely .

    • JVMCBC-858: Channel writeAndFlush failures are no longer ignored.

    • JVMCBC-862: Race condition with node identifier change on bootstrap identified. New logic and some changes to the config provider code ensures that retry and resubscribe picks up fresh seed nodes.

    • JVMCBC-863: Bucket-Level ping report no longer includes other view and KV services buckets.

    • JVMCBC-866: Trailing : no longer added to IPv6 addresses without []. 'invalid IPv6 address' warnings now no longer produced when trying to connect to a valid Ipv6 address thus specified.

    Version 3.0.5 (2 June 2020)

    Version 3.0.5 is the sixth 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.5

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

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

    • org.reactivestreams:reactive-streams:1.0.3


    • JVMCBC-852: Bumped Reactor to 3.3.5, Netty to 4.1.50.Final, and Jackson to 2.11.0.

    • JVMCBC-693: For performance, the KV bootstrap sequence is now partially pipelined.

    In addition, there are internal revisions to support the forthcoming Field Level Encryption (FLE) support. This will be available in a separate library for Enterprise Edition subscribers.

    Bug Fixes

    • JVMCBC-851: Reactive getAllReplicas methods will now honor a provided custom transcoder.

    • JVMCBC-849: Duplicate global loading exceptions are now swallowed to remove redundant warnings from logging (this was a cosmetic-only issue).

    Version 3.0.4 (7 May 2020)

    Version 3.0.4 is the fifth 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.4

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

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

    • org.reactivestreams:reactive-streams:1.0.3


    • JVMCBC-841: Bumped Netty dependency to 2.0.30, and reactor to 3.3.4

    Bug Fixes

    • JVMCBC-845: If a rebalance is stopped in the middle, an edge case occasionally causes KV ops to time out as the fast forward map is chosen over the retry. The behavior has now been changed so that the client will try the old and new servers to make sure the operation eventually gets dispatched to the right node.

    • JCBC-1626: If bucket is not flushable, a BucketNotFlushableException is now raised.

    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.