Retrieving Auto-Failover Settings

  • reference
    Auto-failover settings are retrieved by means of the GET /settings/autoFailover HTTP method and URI.

    HTTP method and URI

    GET /settings/autoFailover


    The GET /settings/autoFailover HTTP method and URI retrieve auto-failover settings for the cluster.

    Auto-failover settings are global, and apply to all nodes in the cluster. To read auto-failover settings, one of the following roles is required: Full Admin, Cluster Admin, Read-Only Admin, Backup Full Admin, Eventing Full Admin, Local User Security Admin, External User Security Admin.

    Curl Syntax

    curl -X GET http://<ip-address-or-hostname>:8091/settings/autoFailover
      -u <username>:<password>


    Success returns 200 OK, and an object that contains the following parameters:

    • enabled. Indicates whether automatic failover is enabled (a value of true) or disabled (a value of false).

    • timeout. Returns an integer between 5 and 3600, which specifies the number of seconds set to elapse, after a node has become unavailable, before automatic failover is triggered. The default value is 120.

    • count. This parameter represents how many auto-failover nodes have occurred since the parameter was itself last reset, to a value of 0, through administrator intervention. The parameter’s default value is 1. Couchbase Server increments this value by 1 for every node that is auto-failed over, up to the administrator-specified maximum count. If nodes are failed over automatically until the maximum count is reached, no further auto-failover is triggered until a parameter-reset is performed.

    • failoverOnDataDiskIssues. This contains two values, which are:

      • enabled, which indicates whether auto-failover can occur when a disk has been unresponsive, and which can be true or false (the default).

      • timePeriod, which indicates the administrator-specified time-period, in seconds, after which auto-failover is triggered, when a disk is unresponsive. The value is an integer between 5 and 3600.

    • maxCount. The administrator-specified maximum number of nodes that can be concurrently auto-failed over. If nodes are auto-failed over until the value of maxCount is reached, no further auto-failover is triggered until a parameter-reset is performed. The default value is 1.

    • canAbortRebalance. Whether or not auto-failover can be triggered if a rebalance is in progress. This feature is only available in Couchbase Enterprise Edition. The value can be either true (the default) or false.

    Failure to authenticate returns 401 Unauthorized. An incorrectly specified URL returns 404 Object Not Found.


    The following example returns the auto-failover settings for the cluster. The output is piped to the jq command, to facilitate readability.

    curl -X GET http://localhost:8091/settings/autoFailover -u Administrator:password | jq '.'

    If successful, execution returns the auto-failover settings for the cluster. For example:

      "enabled": true,
      "timeout": 72,
      "count": 0,
      "failoverOnDataDiskIssues": {
        "enabled": true,
        "timePeriod": 89
      "maxCount": 2,
      "canAbortRebalance": true

    See Also

    For information on setting auto-failover parameters with the REST API, see Enabling and Disabling Auto-Failover.

    The Couchbase CLI allows auto-failover to be managed by means of the setting-autofailover command. For information on managing auto-failover with Couchbase Web Console, see Node Availability.

    A full description of auto-failover is provided in Automatic Failover.