A newer version of this documentation is available.

View Latest

Performing Hard Failover

  • reference
    Hard failover can be used to take a node out of a cluster, when the node has become unresponsive.

    HTTP Method and URI

    POST /controller/failOver


    When a node has become unresponsive, and active vBuckets have thereby become unavailable for the serving of data, hard failover should be used to take the unresponsive node out of the cluster.

    During hard failover, the Cluster Manager promotes replica vBuckets to active status on the remaining cluster-nodes. A revised cluster-map is then communicated to all clients. When hard failover is complete, no further attempts are made to access vBuckets on the failed-over node, but the node has not yet been fully taken out of the cluster. The cluster is at this point considered to be in a degraded state, in terms of availability; as it now contains a reduced number of replica vBuckets, and may lack resources for handling a further node-outage. Rebalance should therefore be performed.

    Hard failover should not be used as part of regular, planned maintenance activities that can be conducted with all cluster-nodes available. For information, see Failover.

    Curl Syntax

    curl -v -X POST -u <username>:<password>
      -d [otpNode=node_1@<hostname>]
      -d allowUnsafe=< true | false >

    The value of each specified otpNode parameter must be the name of a node that will be hard-failed over.

    The value of allowUnsafe must be either true or false (which is the default); indicating whether or not hard failover should be attempted in unsafe mode. For information, see Hard Failover in Default and Unsafe Modes.


    Success returns 200 OK.

    Incorrectly specifying the target cluster returns Failed to connect. Incorrectly specifying the URI returns a 404 Object Not Found error, and a Requested resource not found notification.

    Specifying an unknown server to be failed over returns a 400 Bad Request notification, and an error message such as the following: Unknown server given: ["ns_1@"].

    Failure to authenticate returns a 401 Unauthorized notification.


    The following curl statement performs a hard failover of node from a cluster identified as

    curl -v -X POST -u Administrator:password \ \
    -d 'otpNode=ns_1@'

    The following performs a hard failover of nodes and from a cluster identified as Note that multi-node failover is always hard failover.

    curl -v -X POST -u Administrator:password \ \
    -d 'otpNode=ns_1@' \
    -d 'otpNode=ns_1@'

    The following performs an unsafe, hard failover of nodes and from a cluster identified as

    curl -v -X POST -u Administrator:password \ \
    -d otpNode=ns_1%4010.142.180.102\&otpNode=ns_1%4010.142.180.103 \
    -d allowUnsafe=true

    See Also

    For a general introduction to failover, see Failover. For specifics related to hard failover, including safe and unsafe modes, see Hard Failover. For information on managing different kinds of failover with UI, CLI, and the REST API, see Fail a Node Over and Rebalance. For information on unsafe hard failover, see Hard Failover in Default and Unsafe Modes.