Atlas error: TLS handshake failure connecting to the cluster

TLS handshake failures

Variants you will see: SSL handshake failed, certificate verify failed, tls: first record does not look like a TLS handshake, connection closed during handshake.

Confirm

• first record does not look like a TLS handshake: the client spoke plaintext to a TLS-only port. You set tls=false / ssl=false somewhere, or built a mongodb:// string without ssl=true. Atlas never accepts plaintext.
• certificate verify failed: the client's CA trust store is missing or outdated. Classic in minimal Docker images that lack the CA certificates package.
• Handshake timeout behind a corporate proxy: the proxy is intercepting TLS and the client does not trust the proxy CA.

Fix

• Remove any tls=false override. Let the driver use its default TLS-on behavior with the SRV string.
• Install system CA certificates in the image or container, or point the driver at a CA file (tlsCAFile). Verify the chain; do not set tlsAllowInvalidCertificates=true.
• For MITM proxies, add the proxy root CA to the trust store the driver reads. That is an environment fix, not a driver flag.

Verify

Connect with default TLS settings from the deploy environment. Success there proves the trust chain is fine and the failure was configuration.

Atlas TLS requirements and handshake failure causes per https://www.mongodb.com/docs/atlas/troubleshoot-connection/, verified 2026-09-26.