MongoDB TLS handshake error / tlsInsecure to Atlas in CI

By Daniel Zoghalchali·Latchkey

The driver established a TCP connection to Atlas but the TLS handshake failed because the runner could not validate the server certificate chain. Setting tlsInsecure silences the check rather than fixing trust, so it should be avoided.

What this error means

Connecting to Atlas fails with a TLS error such as "unable to get local issuer certificate" or "SSL routines ... certificate verify failed", while the same URI works from a trusted machine.

MongoServerSelectionError: unable to get local issuer certificate
    at ... (tls handshake) {
  reason: TopologyDescription { type: 'ReplicaSetNoPrimary' }
}

Common causes

An outdated or missing CA bundle on the runner

A slim image with stale ca-certificates cannot validate the certificate chain Atlas presents.

A TLS-inspecting proxy replaces the certificate

A corporate proxy substitutes a certificate signed by a CA not in the runner trust store, so validation fails.

How to fix it

Update the CA store instead of disabling TLS

1. Refresh ca-certificates on the runner so the chain validates.
2. If a proxy injects a CA, add that CA to the trust store.
3. Avoid tlsInsecure/tlsAllowInvalidCertificates outside throwaway debugging.

sudo apt-get update && sudo apt-get install -y ca-certificates
sudo update-ca-certificates

Point the driver at a specific CA bundle

When a proxy CA is required, supply it explicitly rather than turning verification off.

MONGODB_URI="mongodb+srv://.../db?tls=true&tlsCAFile=/etc/ssl/certs/corp-ca.pem"

How to prevent it

• Keep ca-certificates current in custom runner images.
• Add any proxy CA to the trust store, do not disable verification.
• Reserve tlsInsecure for short-lived local debugging only.

Frequently asked questions

Related guides

References

• GitHub Actions documentation