Atlas error: TLS handshake failure connecting to the cluster

TL;DR: Atlas requires TLS. These errors mean the client and server disagreed about encryption. Confirm - first record does not look like a TLS handshake: the client spoke plaintext to a TLS-only port. Atlas never accepts plaintext. - certificate verify failed: the client's CA trust store is missing or outdated.

The error

SSL handshake failed

The fix

1. 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.
2. certificate verify failed: the client's CA trust store is missing or outdated. Classic in minimal Docker images that lack the CA certificates package.
3. Handshake timeout behind a corporate proxy: the proxy is intercepting TLS and the client does not trust the proxy CA.
4. Remove any tls=false override. Let the driver use its default TLS-on behavior with the SRV string.
5. 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.
6. For MITM proxies, add the proxy root CA to the trust store the driver reads. That is an environment fix, not a driver flag.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas error.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Also seen as

• certificate verify failed
• tlsAllowInvalidCertificates=true

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