# Handshake read failed: connection setup problem

## The error

`Handshake read failed` when connecting or querying. The connection attempt fails before any useful work happens.

## Diagnosis order (from the docs)

1. **Client and key setup.** Re-verify the client construction and the API key against the setup docs. A misconfigured client is the most common cause.
2. **Network path.** Firewall or proxy blocking the traffic, or no working internet route. If you are unsure, involve whoever runs the network; this is not fixable in application code.
3. **Reproduce cleanly.** Create a new index and populate it with a small script from the same machine. If that works, the problem is in the original code's configuration, not the machine or the account.
4. **Escalate with evidence.** If it persists, contact support with the index name, timestamps, and the exact error.

## Trap

Tuning TLS settings or retry counts first. This error is about reaching the server at all; retry logic on a connection that cannot handshake is noise. Fix setup, then network, in that order.