Skip to content
MtrXTools

remote error: tls: handshake failure

The server rejected the TLS handshake

Seen in Go (crypto/tls), Docker, Kubernetes tools, Terraform

The server sent a handshake_failure alert because it could not agree on TLS settings with the Go client.

Common causes

  • The server requires a client certificate (mutual TLS) and none was sent.
  • No cipher suite in common: Go does not support some legacy suites such as DHE ones.
  • No SNI, for example when dialling an IP without setting ServerName.

How to fix it

  1. For mutual TLS, load the client certificate into tls.Config Certificates.
  2. Check which ciphers and versions the server offers and enable modern ECDHE suites on it.
  3. Set tls.Config ServerName when connecting by IP.
Check the TLS versions the server accepts

Got a different message? Paste it into the error explainer.

Related errors

All 32 Languages & runtimes errors