Client Settings

  • reference
    The ClusterOptions class enables you to configure .NET SDK options for bootstrapping, timeouts, reliability, and performance. You can configure the client programmatically using JSON config files, Environmental variables settings, XML based configuration such has app.config or web.config files.

    Configuration Basics

    Configuration is essentially the same as SDK 2.x retaining capabilites with less tunable properties. Instead of using a ClientConfiguration object, you would use a ClusterOptions object. For example, to use a custom timeout for Key/Value (K/V) operations you would do something like this:

    // SDK 3.0 custom k/v timeout
    var options = new ClusterOptions
        KvTimeout = TimeSpan.FromMilliseconds(5)
    Fluent Configuration

    you can also build the Cluster Options in a fluent way for example

    var options = new ClusterOptions()
      .WithCredentials(username: "user", password: "password")
      .WithLogging(LoggerFactory.Create(builder =>
          builder.AddFilter("Couchbase", LogLevel.Debug)

    The cluster options are passed into the Cluster object via a constructor:

    var cluster = new Cluster("couchbase://localhost", options);

    Or by using one of the static Cluster.Connect(…​) methods:

    var cluster = Cluster.Connect("couchbase://localhost", options);

    JSON Configuration

    In support of .NET Core, the client can now be configured using JSON config files.

    JSON configuration is only supported for versions of the SDK 2.3.0 and greater running on .NET Core 1.0 or greater.

    Below is an example of how appsettings.json can be coded for cluster options, note the key ClusterOptions is simply a name of an object and can be anything you may want it to be.

      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft": "Warning",
          "Microsoft.Hosting.Lifetime": "Information"
      "AllowedHosts": "*",
      "ClusterOptions": {
        "ConnectionString": "couchbase://localhost",
        "UserName": "user",
        "Password": "password",
        "BucketName" : "travel-sample"

    Here is an example of building the options from the JSON configuration above:

    var settings = Configuration.GetSection("ClusterOptions");

    The options can now be made accessible through any services as below,

    public CustomService ( IOptions<ClusterOptions> clusterOptions)
        var bucketName = clusterOptions.BucketName;

    The "travel-sample" bucket is opened using any of the overridden defaults.

    Configuration Options

    The following tables cover all possible configuration options and explain their usage and default values. The tables categorize the options into groups for bootstrapping, timeout, reliability, performance, and advanced options.

    Security Options

    By default the client will connect to Couchbase Server using an unencrypted connection. If you are using the Enterprise Edition, it’s possible to secure the connection using TLS.

    Template for configuring security settings
    var options = new ClusterOptions()
        EnableTls = true
    Unless you set EnableTls to true, none of the other security settings in this section have any effect.
    Name: Enabling Secure Connections

    Cluster Option: EnableTls(boolean)

    Default: false

    Set this to true to encrypt all communication between the client and server using TLS. This feature requires the Enterprise Edition of Couchbase Server 3.0 or later. If TLS is enabled you must also specify the trusted certificates by calling exactly one of trustCertificate, trustCertificates, or trustManagerFactory. Please see the Managing Connections section for more details on how to set it up properly.

    Name: Enable Certificate Based Authentication

    Cluster Option: EnableCertificateAuthentication(boolean)

    EnableCertificateAuthentication is required to be set to true to use Certificate Authentication

    Name: Ignore Remote Certificate Name Mismatch

    Cluster Option: IgnoreRemoteCertificateNameMismatch(boolean)

    Default: false

    If TLS is enabled via EnableTls, setting this to true will disable hostname validation when authenticating connections to Couchbase Server. This is typically done in test or development environments where a domain name (FQDN) has not been specified for the bootstrap server’s URI, and the IP address is use to validate the certificate, which will fail with a RemoteCertificateNameMismatch error.

    Name: Enable Certificate Revocation

    Cluster Option: EnableCertificateRevocation(boolean)

    Default: false

    A Boolean value that specifies whether the certificate revocation list is checked during authentication.

    I/O Options

    This section provides basic settings that will come in handy while configuring network related operations.

    Template for configuring I/O settings
    var options = new ClusterOptions()
        EnableDnsSrvResolution = true
    Name: DNS SRV Enabled

    Cluster Option: EnableDnsSrvResolution(boolean)

    Default: true

    Gets the bootstrap node list from a DNS SRV record. See the Connection Management section for more information on how to use it properly.

    Name: Mutation Tokens Enabled

    Cluster Options: EnableMutationTokens(boolean)

    Default: true

    Mutation tokens allow enhanced durability requirements as well as advanced SQL++ (formerly N1QL) querying capabilities. Set this to false if you do not require these features and wish to avoid the associated overhead.

    Name: Socket Keepalive

    Cluster Option: EnableTcpKeepAlives(boolean)

    Default: true

    If enabled, the client periodically sends a TCP keepalive to the server to prevent firewalls and other network equipment from dropping idle TCP connections.

    Name: Socket Keepalive Interval

    Cluster Option: TcpKeepAliveTime(TimeSpan)

    Default: 60s

    The idle time after which a TCP keepalive gets fired. (This setting has no effect if EnableTcpKeepAlives is false.)

    This setting only propagates to the OS on Linux when the epoll transport is used. On all other platforms, the OS-configured time is used (and you need to tune it there if you want to override the default interval).
    Name: Key/Value Endpoints per Node

    Cluster Option: NumKvConnections(int)

    Default: 2

    The number of actual endpoints (sockets) to open per node in the cluster against the Key/Value service. By default, for every node in the cluster one socket is opened where all traffic is pushed through. That way the SDK implicitly benefits from network batching characteristics when the workload increases. If you suspect based on profiling and benchmarking that the socket is saturated you can think about slightly increasing it to have more "parallel pipelines". This might be especially helpful if you need to push large documents through it.

    Durable Write operations with Couchbase Server 6.5 and above require up to 16 kvEndpoints per node, for most efficient operation, unless the environment dictates something a little lower.
    Name: Max HTTP Endpoints per Service per Node

    Cluster Option: MaxHttpConnections(int)

    Default: 5

    Each service (except the Key/Value service) has a separate dynamically sized pool of HTTP connections for issuing requests. This setting puts an upper bound on the number of HTTP connections in each pool.

    Name: Enable Config Poll

    Cluster Option: EnableConfigPolling(boolean)

    Default: true

    Enables Configuration heartbeat checks.

    Name: Config Poll Interval

    Cluster Option: ConfigPollInterval(TimeSpan)

    Default: 2.5s

    The interval at which the client fetches cluster topology information in order to proactively detect changes. EnableConfigPolling should be set to true to leverage this setting.

    Circuit Breaker Options

    Circuit breakers are a tool for preventing cascading failures.

    When a circuit is closed, requests are sent to the server as normal. If too many requests fail within a certain time window, the breaker opens the circuit, preventing requests from going through.

    When a circuit is open, any requests to the service immediately fail without the client even talking to the server. After a "sleep delay" elapses, the next request is allowed to go through the to the server. This trial request is called a "canary."

    Each service has an associated circuit breaker which may be configured independently of the others. The IoConfig builder has methods for configuring the circuit breakers of each service.

    Template for configuring circuit breaker settings
    var options = new ClusterOptions()
        CircuitBreakerConfiguration =
        new Couchbase.Core.CircuitBreakers.CircuitBreakerConfiguration
            Enabled = true,
            VolumeThreshold = 45,
            ErrorThresholdPercentage = 25,
            SleepWindow = TimeSpan.FromSeconds(1),
            RollingWindow = TimeSpan.FromMinutes(2)

    The properties of a circuit breaker are described below.


    Default: true

    Enables or disables this circuit breaker.

    If this property is set to false, then the circuit breaker is not used and all other properties are ignored.


    Default: 20

    The volume threshold defines how many operations must be in the window before the threshold percentage can be meaningfully calculated.


    Default: 50

    The percentage of operations in a window that may fail before the circuit is opened. The value is an integer in the range [0,100].


    Default: 5s

    The delay between when the circuit opens and when the canary is tried.


    Default: 1m

    How long the window is in which the number of failed ops are tracked in a rolling fashion.

    Timeout Options

    The default timeout values are suitable for most environments, and should be adjusted only after profiling the expected latencies in your deployment environment. If you get a timeout exception, it may be a symptom of another issue; increasing the timeout duration is sometimes not the best long-term solution.

    Most timeouts can be overridden on a per-operation basis (for example, by passing a custom options block to a "get" or "query" method). The values set here are used as the defaults when no per-operation timeout is specified.

    Template for configuring timeouts
     var options = new ClusterOptions()
        KvTimeout = TimeSpan.FromSeconds(2.5),
        KvDurabilityTimeout = TimeSpan.FromSeconds(10),
        ViewTimeout = TimeSpan.FromSeconds(75),
        QueryTimeout = TimeSpan.FromSeconds(75),
        SearchTimeout = TimeSpan.FromSeconds(75),
        AnalyticsTimeout = TimeSpan.FromSeconds(75),
        ManagementTimeout = TimeSpan.FromSeconds(75)

    Timeout Options Reference

    Name: Key-Value Timeout

    Cluster Option: KvTimeout(TimeSpan)

    Default: 2.5s — but see TIP, below

    The Key/Value default timeout is used on operations which are performed on a specific key if not overridden by a custom timeout. This includes all commands like Get(), GetFromReplica() and all mutation commands, but does not include operations that are performed with enhanced durability requirements.

    Durable Write operations have their own timeout setting, KvDurableTimeout, see below.
    Name: Key-Value Durable Operation Timeout

    Cluster Option: KvDurableTimeout(TimeSpan)

    Default: 10s

    Key/Value operations with enhanced durability requirements may take longer to complete, so they have a separate default timeout.

    Do not set this above 65s, which is the maximum possible SyncWrite timeout on the Server side.

    The KvDurableTimeout property is not part of the stable API and may change or be removed at any time.
    Name: View Timeout

    Cluster Option: ViewTimeout(TimeSpan)

    Default: 75s

    The View timeout is used on view operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows. Also, if there is a node failure during the request the internal cluster timeout is set to 60 seconds.

    Name: Query Timeout

    Cluster Option: QueryTimeout(TimeSpan)

    Default: 75s

    The Query timeout is used on all SQL++ query operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

    Name: Search Timeout

    Cluster Option: SearchTimeout(TimeSpan)

    Default: 75s

    The Search timeout is used on all FTS operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

    Name: Analytics Timeout

    Cluster Option: AnalyticsTimeout(TimeSpan)

    Default: 75s

    The Analytics timeout is used on all Analytics query operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

    Name: Management Timeout

    Cluster Option: ManagementTimeout(TimeSpan)

    Default: 75s

    The management timeout is used on all cluster management APIs (BucketManager, UserManager, CollectionManager, QueryIndexManager, etc.) if not overridden by a custom timeout. The default is quite high because some operations (such as flushing a bucket, for example) might take a long time.

    General Options

    Name: Unordered Execution

    Cluster Option: UnorderedExecutionEnabled

    Default: true

    From Couchbase 7.0, Out-of-Order execution allows the server to concurrently handle multiple requests on the same connection, potentially improving performance for durable writes and multi-document ACID transactions. This means that tuning the number of connections (KV endpoints) is no longer necessary as a workaround where data not available in the cache is causing timeouts.

    This is set to true by default. Note, changing the setting will only affect Server versions 7.0 onwards.

    Name: Transcoder

    Cluster Option: Transcoder(Transcoder)

    Default: JsonTranscoder

    The transcoder is responsible for converting KV binary packages to and from C# objects.

    The default transcoder assumes you are working with JSON documents. It uses the configured jsonSerializer to convert between JSON and C# objects. When writing documents it sets the appropriate flags to indicate the document content is JSON.

    The transcoder configured here is just the default; it can be overridden on a per-operation basis.

    Name: Threshold Tracer

    Cluster Option: WithThresholdTracing(ThresholdOptions)

    Default: ThresholdLoggingTracer

    The default tracer logs the slowest requests per service.

    var clusterOptions = new ClusterOptions();
      clusterOptions.WithThresholdTracing(thresholdOptions =>
    Name: Orphaned Response Tracer

    Cluster Option: WithOrphanTracing(OrphanOptions)

    Default: enabled

    Orphaned Response Logger will log orphaned responses if a request fails to complete for some reason.

    var clusterOptions = new ClusterOptions();
      clusterOptions.WithOrphanTracing(orphanOptions =>

    Commonly Used Options

    The defaults above have been carefully considered and in general it is not recommended to make changes without expert guidance or careful testing of the change. Some options may be commonly used together in certain envionments or to achieve certain effects.

    Constrained Network Environments

    Though wide area network (WAN) connections are not directly supported, some development and non-critical operations activities across a WAN are convenient. Most likely for connecting to Couchbase Capella, or Server running in your own cloud account, whilst developing from a laptop or other machine not located in the same data center. These settings are some you may want to consider adjusting:

    • Connect Timeout to 30s

    • Key-Value Timeout to 5s

    • Config Poll Interval to 10s

    • Circuit Breaker ErrorThresholdPercentage to 75

    As of SDK API 3.4 you can also use a Configuration Profile, which allows you to quickly configure your environment for common use-cases. See the Configuration Profiles section for more details.

    A program using the SDK can also use the waitUntilReady() API call to handle all connection negotiations and related errors at one place. It may be useful to block in, for example, a basic console testing application for up to 30 seconds before proceeding in the program to perform data operations. See the API reference for further details.

    Configuration Profiles

    Configuration Profiles provide predefined client settings that allow you to quickly configure an environment for common use-cases. When using a configuration profile, the current client settings are overridden with the values provided in the profile. Any property that is not specified in the profile is left unchanged.

    The Configuration Profiles feature is currently a Volatile API and may be subject to change.

    WAN Development

    Cluster Option: ApplyProfile("wan-development")

    A wan-development configuration profile can be used to modify client settings for development or high-latency environments. This profile changes the default timeouts.

    Table 1. Profile Settings
    Setting Value