javax.net.ssl.SSLException: Received fatal alert: protocol_version received when connecting to external applications

Article ID:360028518251
1 minute readKnowledge base

Issue

When attempting to connect Jenkins to external applications, you may receive the following error in the logs:

javax.net.ssl.SSLException: Received fatal alert: protocol_version
    at sun.security.ssl.Alerts.getSSLException(Alerts.java:208)
    at sun.security.ssl.Alerts.getSSLException(Alerts.java:154)
    at sun.security.ssl.SSLSocketImpl.recvAlert(SSLSocketImpl.java:2038)
    at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:1135)
    at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1385)
    at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1413)
    at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1397)
    at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:559)
    at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:185)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1564)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1492)
    at java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:480)
    at sun.net.www.protocol.https.HttpsURLConnectionImpl.getResponseCode(HttpsURLConnectionImpl.java:347)

Environment

  • CloudBees Core

  • CloudBees Jenkins Enterprise

  • CloudBees Jenkins Platform

Resolution

This error usually indicates that the incorrect TLS version is being used between Jenkins and the external application. Typically Jenkins expects TLS v1.2 to be used, but older plugins or applications may be using v1.0 or v1.1.

  • First, you can try setting the JVM argument -Dhttps.protocols=TLSv1.2 to make sure that Jenkins only uses TLS v1.2.

    If that does not resolve the issue, then the issue may be with a specific plugin or the external application itself.

  • Make sure that your plugins are up to date and look for any open issues regarding TLS connections if the issue seems to be coming from a specific plugin.

  • Check your external application/server to make sure it is using the correct TLS version (usually 1.2).

    For example, a Windows Team Foundation Server may need to have registry keys similar to the following added to enforce use of TLS v1.2:

32 Bit (DWORD would be 32 bit)
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]
"SchUseStrongCrypto"=dword:00000001

64 Bit (DWORD would be 32 bit)
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
"SchUseStrongCrypto"=dword:00000001