🔐 Vault Error: 'Vault is in standby mode' on HTTP 429 or 473

Exact Error Message

$ vault kv get secret/myapp/config
Error making API request.

URL: GET https://vault-1.example.com:8200/v1/secret/data/myapp/config
Code: 429. Errors:

* Vault is in standby mode

On an Enterprise performance standby or a performance replication secondary you will instead see a 473:

Error making API request.

URL: PUT https://vault-2.example.com:8200/v1/secret/data/myapp/config
Code: 473. Errors:

* Vault is in standby mode

What It Means

A Vault HA cluster runs several unsealed nodes, but only one holds the leader lock and is active. Every other node is a standby: it is unsealed and listening on its API port, but it does not serve requests from its own storage. Normally a standby transparently forwards your request over the cluster port to the active node and returns the result, so you never notice which node you hit. The 429 means forwarding did not happen — the standby had to answer for itself, and the only answer it has is “I am not the active node.”

The 473 is a related but distinct signal. It is returned by a performance standby (Vault Enterprise) or a performance replication secondary for a request that must be handled by the primary — typically any write, or a read that needs to create a token or lease. A client library that understands 473 retries against the primary; a plain curl or an old SDK just surfaces the error. In both cases the fix is the same class of problem: either forwarding is broken (usually api_addr/cluster_addr or disable_clustering), or something in front of Vault is routing traffic to a node that cannot serve it.

Common Causes

• cluster_addr is unset or wrong on one or more nodes, so standbys cannot reach the active node’s cluster port.
• api_addr is set to 127.0.0.1 or a per-node hostname that other nodes and clients cannot resolve.
• disable_clustering = true in the storage stanza, which turns off request forwarding entirely.
• A firewall or security group allows 8200 between nodes but not the cluster port 8201.
• The load balancer health check hits /v1/sys/health with default parameters, so standbys are marked unhealthy — or, worse, uses a TCP check and keeps sending traffic to a sealed or standby node.
• The client explicitly sends X-Vault-No-Request-Forwarding, which tells the standby not to forward.

Diagnostic Commands

Ask each node directly what it thinks its HA role is:

vault status -address=https://vault-1.example.com:8200
vault status -address=https://vault-2.example.com:8200

Look at the HA Enabled, HA Cluster, HA Mode, and Active Node Address fields. HA Mode: standby with a populated Active Node Address is normal and healthy.

Query the health endpoint the way a load balancer would, and inspect the status code rather than the body:

curl -s -o /dev/null -w '%{http_code}\n' https://vault-2.example.com:8200/v1/sys/health
curl -s -o /dev/null -w '%{http_code}\n' 'https://vault-2.example.com:8200/v1/sys/health?standbyok=true'

The first returns 429 for a standby; the second returns 200. That single difference explains most “the LB says every node is down” incidents.

Read the cluster’s own view of leadership:

curl -s https://vault-1.example.com:8200/v1/sys/leader | jq

Confirm the advertised addresses each node published:

grep -E 'api_addr|cluster_addr|disable_clustering' /etc/vault.d/vault.hcl

Verify the cluster port is actually reachable between nodes:

nc -vz vault-1.example.com 8201

If you use Raft storage, list the peers and check every node is present with the address you expect:

vault operator raft list-peers

Step-by-Step Resolution

1. Identify the real active node and confirm it serves requests. Point directly at the address from Active Node Address and re-run your call:

vault status | grep -i 'active node'
VAULT_ADDR=https://vault-1.example.com:8200 vault kv get secret/myapp/config

If that succeeds, the cluster is fine and the problem is routing or forwarding, not Vault’s data.

2. Fix api_addr and cluster_addr on every node. Each must be an address that other cluster members and clients can reach — never a loopback address:

listener "tcp" {
  address       = "0.0.0.0:8200"
  cluster_address = "0.0.0.0:8201"
  tls_cert_file = "/etc/vault.d/tls/vault.crt"
  tls_key_file  = "/etc/vault.d/tls/vault.key"
}

api_addr     = "https://vault-2.example.com:8200"
cluster_addr = "https://vault-2.example.com:8201"

3. Remove disable_clustering if it was set. With clustering disabled, standbys cannot forward and every request to a standby returns 429:

storage "raft" {
  path    = "/opt/vault/data"
  node_id = "vault-2"
  # disable_clustering = true   <- delete this
}

Restart the node and re-check HA Cluster in vault status:

systemctl restart vault
vault status

4. Open the cluster port between all nodes. Forwarding uses a separate mutually-authenticated TLS connection on cluster_addr, so allowing 8200 alone is not enough:

sudo firewall-cmd --permanent --add-port=8201/tcp
sudo firewall-cmd --reload

5. Point the load balancer health check at /v1/sys/health with parameters that match your intent. To send traffic only to the active node, use the default (standbys answer 429 and drop out of the pool). To let standbys serve forwarded traffic, mark 429 as healthy or pass standbyok=true:

# Active-only pool
GET /v1/sys/health              -> healthy: 200

# Any unsealed node (forwarding does the rest)
GET /v1/sys/health?standbyok=true&perfstandbyok=true   -> healthy: 200

Never use a bare TCP check on 8200: a sealed node still accepts TCP connections, so it will stay in the pool and every request will fail. If sealed nodes are your actual symptom, see Vault error: “Vault is sealed”.

6. If you need to move leadership deliberately — for a rolling upgrade or to drain a node — force the active node to relinquish the lock rather than killing the process:

VAULT_ADDR=https://vault-1.example.com:8200 vault operator step-down
vault status | grep -i 'active node'

For generating load balancer health-check configurations and HA-aware Vault listener stanzas from your topology, the Vault prompts in the prompt library can produce a reviewed starting config.

Prevention

• Template api_addr and cluster_addr per node from the instance’s real DNS name; never leave them at defaults or loopback.
• Always health-check /v1/sys/health over HTTP, never a raw TCP port check, so sealed nodes leave the pool.
• Decide once whether your LB pool is active-only or all-unsealed, and encode the standbyok/perfstandbyok choice in the check.
• Allow both 8200 and the cluster port 8201 between all Vault nodes in security groups and host firewalls.
• Use official Vault client libraries, which understand 473 and retry against the primary, instead of hand-rolled HTTP calls.
• Alert on HA Mode flapping — repeated leadership changes usually indicate storage latency or network partitions rather than a config error.

Related Errors

• Vault is sealed (HTTP 503) — the node is unsealed-pending, a different state from standby; it cannot forward anything.
• connection refused on /v1/sys/seal-status — the process is not listening at all, not an HA routing problem.
• local node not active but active cluster node not found — forwarding is enabled but the standby cannot locate or reach the leader.
• missing client token — an authentication problem that can surface after you finally reach the active node.

Frequently Asked Questions

Is 429 from Vault a rate limit? No. Vault reuses the 429 status code to mean “standby node” on /v1/sys/health, which is why generic HTTP tooling and some LB templates misinterpret it. Judge it by the endpoint and the Vault is in standby mode body, not the code alone.

Why does reading work but writing fail with 473? A performance standby can serve many reads from its local cache but must send writes — and anything that creates a token or lease — to the active node or replication primary. 473 is the explicit “forward me to the primary” signal.

Should I ever set X-Vault-No-Request-Forwarding? Only for diagnostics, when you deliberately want a specific node to answer for itself so you can confirm its role. In normal client traffic it converts a working forwarded request into a 429.

How do I safely fail over during maintenance? Run vault operator step-down on the active node, confirm a new Active Node Address in vault status, then patch the now-standby node. If clients start failing right after failover with auth errors, check Vault error: “permission denied” and the rest of the Vault guides.