## TL;DR

TLS errors mean the client does not trust the server's certificate or they cannot agree on TLS settings. Install the right CA bundle, check the server name, and verify TLS versions match.

## Error

```text
agent's vault client crashed with tls error
```

## Steps

1. Read the exact TLS error: unknown authority, hostname mismatch, or handshake failure each point differently. Expected: the specific failure.
2. For unknown authority, install the Vault CA certificate into the client's trust store. Expected: the chain verifies.
3. For hostname mismatch, check the client connects with the name on the certificate. Expected: names match.
4. For handshake failures, check TLS version and cipher overlap. Expected: a common version exists.
5. Retry the client connection. Expected: TLS establishes.

## When to use

- Vault client TLS failures in agents.
- Setting up Vault TLS.

## When not to use

- Auth failures after TLS works.
- Permission errors.

## Tool compatibility

- Vault API clients; TLS CA bundles.

## Variant phrasings

### vault tls handshake failed

Version or cipher mismatch.

### certificate verify failed vault

CA trust issue.

## Why it happens

Internal Vault instances use private CAs that clients do not trust by default, and TLS settings drift between client and server.

## Edge cases

- Disabling verification is never the fix; install the CA.
- Rotated server certificates need the new CA distributed.
- Proxies that terminate TLS need their CA trusted too.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ptPGb3pVAtddoPOKF-AXcg