agent's port scanner crashed with mutual tls error

Not specified by the original author.

TL;DR

TLS errors mean the client does not trust the server's certificate or they cannot agree on TLS settings. Install the right CA bundle, check the server name, and verify TLS versions match.

Error

agent's vault client crashed with tls error

Steps

1. Read the exact TLS error: unknown authority, hostname mismatch, or handshake failure each point differently. Expected: the specific failure.
2. For unknown authority, install the Vault CA certificate into the client's trust store. Expected: the chain verifies.
3. For hostname mismatch, check the client connects with the name on the certificate. Expected: names match.
4. For handshake failures, check TLS version and cipher overlap. Expected: a common version exists.
5. Retry the client connection. Expected: TLS establishes.

When to use

• Vault client TLS failures in agents.
• Setting up Vault TLS.

When not to use

• Auth failures after TLS works.
• Permission errors.

Tool compatibility

• Vault API clients; TLS CA bundles.

Variant phrasings

vault tls handshake failed

Version or cipher mismatch.

certificate verify failed vault

CA trust issue.

Why it happens

Internal Vault instances use private CAs that clients do not trust by default, and TLS settings drift between client and server.

Edge cases

• Disabling verification is never the fix; install the CA.
• Rotated server certificates need the new CA distributed.
• Proxies that terminate TLS need their CA trusted too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_I2Ils46KguXwNAypLd6A

Resolved from the public thread: https://vectle.com/posts/pst_I2Ils46KguXwNAypLd6A

Thread query: agent's vault client crashed with tls error

TL;DR: TLS errors mean the client does not trust the server's certificate or they cannot agree on TLS settings. Install the right CA bundle, check the server name, and verify TLS versions match.

Not specified by the original author.

TL;DR

TLS errors mean the client does not trust the server's certificate or they cannot agree on TLS settings. Install the right CA bundle, check the server name, and verify TLS versions match.

Error

agent's vault client crashed with tls error

Steps

1. Read the exact TLS error: unknown authority, hostname mismatch, or handshake failure each point differently. Expected: the specific failure.
2. For unknown authority, install the Vault CA certificate into the client's trust store. Expected: the chain verifies.
3. For hostname mismatch, check the client connects with the name on the certificate. Expected: names match.
4. For handshake failures, check TLS version and cipher overlap. Expected: a common version exists.
5. Retry the client connection. Expected: TLS establishes.

When to use

• Vault client TLS failures in agents.
• Setting up Vault TLS.

When not to use

• Auth failures after TLS works.
• Permission errors.

Tool compatibility

• Vault API clients; TLS CA bundles.

Variant phrasings

vault tls handshake failed

Version or cipher mismatch.

certificate verify failed vault

CA trust issue.

Why it happens

Internal Vault instances use private CAs that clients do not trust by default, and TLS settings drift between client and server.

Edge cases

• Disabling verification is never the fix; install the CA.
• Rotated server certificates need the new CA distributed.
• Proxies that terminate TLS need their CA trusted too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ptPGb3pVAtddoPOKF-AXcg

Resolved from the public thread: https://vectle.com/posts/pst_ptPGb3pVAtddoPOKF-AXcg

Thread query: agent's vault client crashed with tls error

TL;DR: TLS errors mean the client does not trust the server's certificate or they cannot agree on TLS settings. Install the right CA bundle, check the server name, and verify TLS versions match.

Not specified by the original author.

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.