Couchbase Java SDK Release Notes and Archives

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

    These pages cover the 3_x_ 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.2.0 (20 July 2021)

    Version 3.2.0 is the first release of the 3.2 series. It promotes to GA support for the scopes and collections provided by Couchbase Server 7.0, and also OpenTelemetry.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.6

    • org.reactivestreams:reactive-streams:1.0.3

    Bug Fixes

    • JVMCBC-949: Opening a non-default collection on an memcached bucket now fails fast.

    • JVMCBC-983: Ignore slow subscribers on certain Flux intervals.

    • JCBC-1822: BatchHelper now supports MDS deployments.

    Interface Changes

    All interface changes are to interfaces that are currently in beta and marked @Stability.Volatile or @Stability.Uncommitted.

    • JVMCBC-978: Rename AggregatingMeter to LoggingMeter.

    • JVMCBC-934: Threshold and Orphan output is now in new format.

    • JVMCBC-979: Rename ThresholdRequestTracer to ThresholdLoggingTracer.

    • JCBC-1823: Promote collection APIs from Volatile to Committed.

    • JCBC-1844: Promote BatchHelper from Volatile to Uncommitted.


    • JVMCBC-980: Add exception wrappers to Tracers and Meters.

    • JVMCBC-987: Allow supplying an SDK2-compatible memcached hashing strategy.

    • JVMCBC-988: Map Query Error 13014 to AuthenticationException.

    • JVMCBC-989: Add timeout_ms to threshold logging tracer output.

    • JVMCBC-991: Optimize metric dispatching.

    • JVMCBC-992: Cache NodeIdentifier in NodeInfo.

    • JVMCBC-993: Optimize early discard of events which are not going to be logged.

    • JVMCBC-996: Throw FeatureNotAvailableException if scope level queries are not available.

    • JVMCBC-997: Duplicate attributes from dispatch_to_server to improve tracing.

    • JVMCBC-998: Performance: Do not set tracing spans if not needed.

    • JVMCBC-981: Support CoreHttpClient requests to manager service.

    • JVMCBC-984: Dependency bump: Netty 4.1.63 to 4.1.65, micrometer 1.6.6 to 1.7.0.

    • JCBC-1242, JCBC-1837: Add OSGi bundle.

    • JCBC-1787: Validate expiry instants.

    • JCBC-1838: Add support for SDK2-compatible LegacyTranscoder.

    • JCBC-1841: Update OpenTelemetry to 1.3.0.

    Version 3.1.6 (4 June 2021)

    Version 3.1.6 is the seventh release of the 3.1 series, bringing stabilizations and enhancements over 3.1.5.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.6

    • org.reactivestreams:reactive-streams:1.0.3

    Bug Fixes

    • JCBC-1676: Bucket creation now succeeds against Community Edition 6.5 and above.

    • JVMCBC-972: Only open one GCCCP connection per node.


    • JCBC-1808: Updated tracing and metrics module dependencies.

    • JCBC-1649: Update analytics management API to support compound dataverse names.

    • JCBC-1815: Improve error context for BatchHelper.

    • JVMCBC-939: Improve no collection access handling.

    • JVMCBC-974: Restructure AggregatingMeter output format.

    • JVMCBC-975: Further improve wait until ready diagnostics.

    • JVMCBC-977: Improve bucket configuration handling (revEpoch).

    Version 3.1.5 (6 May 2021)

    Version 3.1.5 is the sixth release of the 3.1 series, bringing stabilizations and enhancements over 3.1.4.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.5

    • org.reactivestreams:reactive-streams:1.0.3

    Bug Fixes

    • JCBC-1804: Ensure contentAsObject/Array() works with a custom JsonSerializer.

    • JVMCBC-965: Better error logging during bucket failures, which helps with troubleshooting.

    • JVMCBC-963: Add better retry handling for local and global bucket config fetch failures, making it more resilient.

    • JVMCBC-967: Work around and fix a OverflowException with PersistTo/ReplicateTo, caused by Reactor.


    • JVMCBC-958: Improve the performance of individual collection ID fetches, speeding up the time of bootstrap whan a lot of collections are opened.

    • JCBC-1756: Adds volatile support for preserving the expiry on certain mutation operations.

    • JVMCBC-959: Allow IoEnvironment config to be overridden by system properties.

    • JCBC-1801: Allow to create a SearchIndex from a JSON definition.

    • JVMCBC-962: Add (internal, volatile) request callback functionality.

    • JCBC-1733: Add support for collections to SearchOptions.

    Version 3.1.4 (7 April 2021)

    Version 3.1.4 is the fifth release of the 3.1 series, bringing stabilizations and enhancements over 3.1.3.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.4

    • org.reactivestreams:reactive-streams:1.0.3

    Due to protocol level changes, Java SDK 3.1.4 and later are not compatible with pre-release versions of Couchbase Server 7.0.

    Bug Fixes

    • JCBC-1798: Fixes ViewResult.metaData() throwing Exception when debug=true.

    • JVMCBC-940: Better error handling of collection ID fetch failures.

    • JVMCBC-948: CAS is only usable with Sub-Document when using StoreSemantics.REPLACE. This server-side restriction is now also checked client-side, and a InvalidArgumentException raised.

    • JVMCBC-950: waitUntilReady is now more resilient to just-created buckets.

    • JVMCBC-954: More resilient handling of rebalances.


    • JCBC-1786: Transcoders now allow contentAs(Object.class). Java Map and List collections are used to represent JSON objects and arrays.

    • JCBC-1795: Allow MutateInSpec.remove(""), which removes the entire document.

    • JVMCBC-936: Allow customizing TLS cipher list.

    • JVMCBC-941: Support modified protocol for collections in Couchbase Server 7.0 (in beta).

    • JVMCBC-943: Apply OpenTelemetry best practices.

    • JVMCBC-944: Add implementation version to OpenTelemetry APIs.

    • JVMCBC-947: Remove request counter metric.

    • JVMCBC-951: Move GetAny/AllReplicas into core.

    • JVMCBC-955: Distinguish between CAS mismatch and DML failure on query error.

    Version 3.1.3 (2 March 2021)

    Version 3.1.3 is the fourth release of the 3.1 series, bringing stabilizations and enhancements over 3.1.2.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.3

    • org.reactivestreams:reactive-streams:1.0.3


    • JCBC-1776, JVMCBC-924, JVMCBC-925: Updated dependencies: OpenTelemetry to 1.0.0, Netty dependency to 4.1.59, netty-tcnative-boringssl-static to 2.0.36, Reactor to 2.4.3, Jackson to 2.12.1.

    • JCBC-1774: Added pre-flight sanity check before using a JacksonJsonSerializer found on the classpath.

    • JVMCBC-919: Support for Project Reactor BlockHound integration.

    • JVMCBC-926: Performance: Replace new byte[] full copies with ByteBufUtil.getBytes.

    • JVMCBC-927: Performance: Improve performance of metrics hot code path.


    • JVMCBC-930: Threshold and Orphan Reporting now report the correct time units.

    • JVMCBC-932: Fixed a memory leak when OrphanReporter is disabled.

    • JVMCBC-933: ThresholdRequestTracer and OrphanReporter now use bounded queues.

    Internal Improvements

    Version 3.1.2 (2 February 2021)

    Version 3.1.2 is the third release of the 3.1 series, bringing stabilizations and enhancements over 3.1.1.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.1

    • org.reactivestreams:reactive-streams:1.0.3

    API Affecting

    • JCBC-1763: CollectionManager::getScope is now deprecated, in favour of using getAllScopes.


    • JVMCBC-915: As a performance optimization, loading a collection now only fetches the information required for that collection, rather than the full collection manifest.

    • JVMCBC-916: Any send HTTP request will send a hostname if hostnames are used, rather than IP, leading to consistent hostname use across the system.

    Version 3.1.1 (12 January 2021)

    Version 3.1.1 is the second release of the 3.1 series, bringing stabilizations and enhancements over 3.1.0.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.1

    • org.reactivestreams:reactive-streams:1.0.3

    API Affecting

    • JVMCBC-906: Removed Tracer as a mandatory argument from OpenTelemetrySpan. (The OpenTelemetry module is marked @Stability.Volatile, indicating that there may be API-breaking changes. The volatility arises from the underlying OpenTelemetry library itself being at a beta/volatile level.)


    • JVMCBC-909: Retry opening the bucket until timeout when it is not found, to allow for it not yet being created.

    • JVMCBC-910: WaitUntilReady will now wait if bucket not present yet, before it starts to time out.

    • JVMCBC-911, JCBC-1728: Certain collection-related error codes have changed.

    • JCBC-1730: Support for collections added to BatchHelper.

    • JCBC-1747: Prepared non-adhoc queries on scopes were failing, as query_context was not being passed to the individual prepare and/or execute statements. This has now been fixed, and scope-level queries are working as expected.


    • JVMCBC-907: The Orphan Reporter can now be disabled.

    • JVMCBC-908: Updated OpenTelemetry to 0.13.

    • JCBC-1749: Escape the scope for scope-level queries now enabled, as a fix in the server means that this works.

    • JCBC-1746: Expose partition information from the query management API on QueryIndex class.

    Version 3.1.0 (2 December 2020)

    Version 3.1.0 is the first GA release of the 3.1 series, bringing stabilizations and enhancements over 3.0.10 and the 3.0 SDK, and adding features to support Couchbase Server 6.6 and 7.0β.

    The supported and tested dependencies for this release are:

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

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

    • io.projectreactor:reactor-core:3.4.0

    • org.reactivestreams:reactive-streams:1.0.3


    • JCBC-1731: Experimental support for Metrics (Meter) and the internals have been reworked around the RequestTracer. The new metrics implementation is disabled by default but will be enabled in the future. We encourage you to try it out and provide feedback, please see the documentation section on tracing and metrics for further information.

    • JCBC-1646: The minimum durability level can now be configured on the BucketManager.

    • JVMCBC-904: Internal and external dependencies have been updated, including project reactor to 3.4.0.

    • JVMCBC-905: It is now possible to disable TLS hostname verification as part of the SecurityConfig.

    • JVMCBC-901: Support for transactions with N1QL queries has been added to the core subsystem so that the upper transaction dependency can make use of it.

    In addition to the tickets outlined below, different interfaces have been elevated from Uncomitted or Volatile to Comitted. These include:

    • Expiry Key/Value read and write APIs that take an Instant.

    • Geo-Polygon Search

    • Search Flex-Index Option

    • Search Disable-Scoring Option

    Version 3.0.10 (3 November 2020)

    Version 3.0.10 is a maintenance release, bringing enhancements over the last stable release.

    The supported and tested dependencies for this release are:

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

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

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

    • org.reactivestreams:reactive-streams:1.0.3


    • JVMCBC-898: Added fallback for lastDispatchedTo in context, to improve debuggability.

    • JVMCBC-899: Updated OpenTelemetry to 0.9.1.

    Version 3.0.9 (7 October 2020)

    Version 3.0.9 is a bugfix 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.9

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

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

    • org.reactivestreams:reactive-streams:1.0.3

    API Affecting

    • JCBC-1716: The Analytics getPendingMutations API had a return value (Map<String, Long>) that did not reflect what was returned from the server. The return value has been changed to Map<String, Map<String, Long>> accordingly. As the getPendingMutations method was previously uncallable due to the resulting deserialization failure, we believe this API change - though technically breaking - will not impact any users, and we have kept the API version at 3.x.

    Bug Fixes

    • JCBC-1713: Improve LDAP auth failure handling.

    • JCBC-1718: Expiry fixed for touch and getAndTouch methods.

    • JVMCBC-885: Allow overriding of BestEffortRetryStrategy.

    • JVMCBC-889: Make sure WaitUntilReady always times out.

    • JVMCBC-890: Enforce only negotiate PLAIN when using TLS with PasswordAuthenticator.

    • JVMCBC-892: Service pool idle time check must happen more often.

    • JVMCBC-894: BatchHelper: handle success case with no body gracefully.

    • JVMCBC-872: Subdoc 'no access' error code is now reported correctly. This helps users to identify and fix permissions errors for system XATTRs.


    • JCBC-1651: Geopolygon search support.

    • JCBC-1652: Added Options To Use FTS Hints (Flex Index).

    • JCBC-1695: Added support to pass Score as FTS parameter.

    • JCBC-1707: Retrofited Geo Search Queries to allow Coordinate Usage.

    • JCBC-1709: Allow to access ReactiveScope from Scope.

    • JCBC-1712: Clarified Javadoc lockTime on getAndLock.

    • JCBC-1715: Allow to provide custom http headers for the RawManager.

    • JCBC-1717: Support for targeting requests to a given node. This allows to always send QueryRequests related to a given transaction to the same query node.

    • JVMCBC-888, JVMCBC-893: Dependency bumps: Netty to 4.1.52.Final, OpenTelemetry to 0.8.

    • JVMCBC-886: Improve LDAP auth failure handling.

    • JVMCBC-896: Fast dispatch pooled requests.

    Version 3.0.8 (31 August 2020)

    Version 3.0.8 is a bugfix 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.8

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

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

    • org.reactivestreams:reactive-streams:1.0.3


    • JCBC-1705: A (uncomitted) API has been added which allows to very efficiently perform bulk fetch and bulk exists operations. See the BatchHelper class for more details.

    • JCBC-1684: The PingOptions services can now be configured through a vararg, making it easier to use.

    • JCBC-1691: A (uncomitted) API has been added which allows sending all kinds of requests to the cluster manager (called raw manager API).

    • JVMCBC-883: The client is now a little less verbose when performing a DNS SRV request and the underlying JDK operation times out.

    • JVMCBC-879: Updated internal and external dependencies to their latest maintenance releases.

    • JVMCBC-871: On the IoConfig it is now possible to captureTraffic() with empty arguments, implying that all traffic will be captured.

    • JVMCBC-874: When dealing with unknown collections, the SDK now returns a more user friendly retry reason when it can (outdated manifest vs. collection not found).

    • JVMCBC-875: On the request timeout exception, the retry reasons are now accessible directly.

    • JCBC-1693: The UserManager API has been extended to support collections and scopes (needs at least Server 7.0 to be usable).

    • JCBC-1660: Support for scope-level N1QL queries has been added (needs at least Server 7.0 to be usable).

    • JCBC-1658: Support for scope-level analytics queries has been added (needs at least Server 7.0 to be usable).

    Bug Fixes

    • JCBC-1696: When adding the option withExpiry(true) to GetOptions, it is now possible to use a custom transcoder which is JSON compatible.

    • JVMCBC-805: The client now handles bootstrapping against nodes much better which do not have the data service enabled (in an MDS setup).

    • JVMCBC-882: A bug has been fixed where when bootstrapping against a node with no data service enabled, the endpoint would not be cleaned up and would keep trying to reconnect.

    • JVMCBC-872: The client now more explicitly handles an error response code (NO_ACCESS) when a subdocument request is performed against a system xattr.

    • JVMCBC-873: Durability information is now properly unwrapped from an optional when exported and dumped (for example as part of an exception).

    • JVMCBC-880: The client now trackes multiple parallel bucket open attempts (against different buckets) in a better way, making sure that an internal state is only switched when all those bucket open attempts have completed (and not just the first one).

    • JVMCBC-878: EndpointDiagnostics had the local and remote hostnames mixed up, they now show up in the correct order.

    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 CollectionsExample TTL. CreateCollection CollectionSpec now includes MaxTTL.

    • JCBC-1617: Attempting to work with the collection manager on clusters where CollectionsExample 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.

    Older Releases

    Although no longer supported, documentation for older releases continues to be available in our docs archive.