Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Email delivery

Jakarta Mail throws MessagingException: Could not convert socket to TLS

Errorjakarta.mail.MessagingException: Could not convert socket to TLS

Short answer

The server accepted STARTTLS, but the TLS handshake that followed failed on your side. Turn on mail debug output and read the exception under the message. It is nearly always an untrusted certificate, something between you and the server that rewrites the connection, or a TLS protocol list that does not match.

  • Applies to Jakarta Mail 2.x, Angus Mail 2.0, JDK 17, JDK 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Switch on the protocol trace and read the nested exception that follows the message; it names the real handshake failure.

    Properties props = new Properties();
    props.put("mail.smtp.host", "smtp.example.com");
    props.put("mail.smtp.starttls.enable", "true");
    Session session = Session.getInstance(props);
    session.setDebug(true);
  2. 2Match what you see, then jump to its fix

    1. 1The nested exception says unable to find valid certification path to requested target.The server certificate is not trusted by the JVMFix
    2. 2The same code works from another network, or the certificate shown in the debug trace is not your mail provider's.A firewall, antivirus or proxy rewrites the TLS connectionFix
    3. 3The nested exception is a handshake failure about protocol or cipher, not about a certificate path.The enabled TLS protocols do not match what the server acceptsFix

What does the error look like?

  • jakarta.mail.MessagingException: Could not convert socket to TLS
  • javax.mail.MessagingException: Could not convert socket to TLS
  • unable to find valid certification path to requested target

Cause 1 of 3

The server certificate is not trusted by the JVM

1Check

The mail library follows the JVM trust store. With STARTTLS enabled, that store has to be set up correctly. A self-signed or private-CA certificate, or an application server that replaces the JDK's trusted authorities, produces this error.

ls -l "$JAVA_HOME/lib/security/cacerts"

2Fix

For a server you control, trust that one host in the session properties. Prefer importing its certificate into the trust store the JVM really uses, and avoid the * wildcard in production.

props.put("mail.smtp.ssl.trust", "smtp.example.com");

// or point the JVM at a trust store that contains the certificate
// java -Djavax.net.ssl.trustStore=/etc/ssl/mail-truststore.jks MyApp

3Verify

Send again with debug on; the STARTTLS handshake completes and the session moves on to login.

java -Djavax.net.ssl.trustStore=/etc/ssl/mail-truststore.jks MyApp

Confirmed by eclipse-ee4j.github.io

Did this fix it?

Cause 2 of 3

A firewall, antivirus or proxy rewrites the TLS connection

1Check

The Jakarta Mail FAQ lists a firewall or antivirus that intercepts the connection as a cause of certificate path failures. Run the same code from another network or machine; if it works there, something on the first network sits in the middle.

java -Dmail.debug=true MyApp

2Fix

Ask for the mail host to be excluded from TLS inspection, or put the inspection tool's CA certificate in a trust store file and start the JVM with it.

java -Djavax.net.ssl.trustStore=/etc/ssl/mail-truststore.jks MyApp

3Verify

The same send now passes the handshake and reaches the login step in the trace.

java -Dmail.debug=true -Djavax.net.ssl.trustStore=/etc/ssl/mail-truststore.jks MyApp

Confirmed by eclipse-ee4j.github.io

Did this fix it?

Cause 3 of 3

The enabled TLS protocols do not match what the server accepts

1Check

mail.smtp.ssl.protocols sets the protocols enabled for SSL connections as a whitespace-separated list, and the JVM can also restrict them: jdk.tls.client.protocols replaces the client defaults with the list you give.

grep -rn "ssl.protocols\|jdk.tls.client.protocols" src/ pom.xml run.sh 2>/dev/null

2Fix

Remove stale overrides first. If you must set one, list a protocol the server really supports, for example TLSv1.2.

props.put("mail.smtp.ssl.protocols", "TLSv1.2");

3Verify

Run the send again with debug on and watch the handshake finish.

java -Dmail.debug=true MyApp

Confirmed by eclipse-ee4j.github.io

Did this fix it?

How do I stop it coming back?

  • Keep a debug switch (setDebug or -Dmail.debug=true) in your app's config so the nested exception is one flag away.
  • Do not trust all hosts with the * wildcard outside a test machine.
  • Test from the machine that runs the app, not only from your laptop; the network in between can differ.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Email

Django send_mail fails or hangs with an SSL error

smtplib.SMTPException raised from send_mail()

Django has two secure modes that must not be mixed: EMAIL_USE_TLS for explicit TLS (STARTTLS, usually port 587) and EMAIL_USE_SSL for implicit TLS (usually port 465).

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.