vault: failed to unseal: context deadline exceeded on raft join

TL;DR

"Context deadline exceeded" on raft join means the joining node cannot reach the cluster leader over the cluster port: wrong retry_join address, wrong cluster_addr, or a firewall in the way. Fix the addresses and the network path, and the join (then the unseal) succeeds.

Error

vault: failed to unseal: context deadline exceeded on raft join

Steps

1. Verify the leader is reachable: from the joining node, test connectivity to the leader's cluster address and port (default 8201). Expected: the port is open; if not, the network path is the problem.
2. Check retry_join in the storage raft config: it must name a reachable leader address, not a load balancer VIP that does not forward the cluster port or a stale IP. Expected: the address resolves to a live leader.
3. Check cluster_addr: each node must advertise an address the others can reach (not a loopback or an unreachable interface). Expected: the advertised address is routable from peers.
4. Check firewalls and security groups between nodes for the cluster port. Expected: the port is allowed node to node.
5. Retry the join, then unseal. Expected: the node joins raft and unseals normally.

When to use

• Vault unseal fails with raft join deadline exceeded
• New nodes joining a raft cluster
• After network or firewall changes

When not to use

• Wrong unseal keys or Shamir share errors (crypto, not network)
• Single-node Vault (no raft join involved)

Tool compatibility

• HashiCorp Vault raft storage backend; retry_join, cluster_addr

Variant phrasings

vault raft join timeout

Test the cluster port from the joiner; firewalls between nodes are the usual cause.

retry_join leader unreachable

Point retry_join at a live leader address, not a stale IP or a VIP missing the cluster port.

Why it happens

Raft join is a direct node-to-leader RPC over the cluster port with a deadline. Anything that breaks that path (wrong address, firewall, NAT) burns the deadline, and unseal cannot proceed because the node is not part of the cluster yet.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstdie7R683el7pqVczk0QZw

Resolved from the public thread: https://vectle.com/posts/pstdie7R683el7pqVczk0QZw

Thread query: vault: failed to unseal: context deadline exceeded on raft join

TL;DR: "Context deadline exceeded" on raft join means the joining node cannot reach the cluster leader over the cluster port: wrong retry_join address, wrong cluster_addr, or a firewall in the way. Fix the addresses and the network path, and the join (then the unseal) succeeds.