TLS Error with Ruby Client and Tomcat Server

Temporarily work around the problem with a simple client-side hack.

If your Ruby is compiled against a recent version of OpenSSL (1.0.0 and up), there is a good chance you will run into frustrating TLS errors when trying to connect to an HTTPS site hosted by Apache Tomcat. An easy workaround is to set ssl_version = :SSLv3 on the client side.

Update: The better solution is to reconfigure Tomcat, because SSLv3 is known to be vulnerable to attacks. Proceed with caution!

Who’s affected?

Trouble happens when your Ruby is compiled against OpenSSL 1.0 and you try connecting to a Tomcat 7 server using HTTPS. Here’s how to check on your Ruby installation:

$ ruby -r openssl -e 'puts OpenSSL::OPENSSL_VERSION'
OpenSSL 1.0.0e 6 Sep 2011

When you connect to an affected Tomcat 7 server, you’ll be greeted with a vague tlsv1 alert internal error error that looks something like this:

SSL_connect returned=1 errno=0 state=SSLv2/v3 read server hello A: tlsv1 alert internal error

An easy workaround

If you control the Tomcat server, you can modify Tomcat’s configuration to restrict the ciphers Tomcat uses and eliminate the problem.

Otherwise, working around the problem on the client side in Ruby is straightforward. When using Net::HTTP, just set ssl_version = :SSLv3:1

http =, port)
http.use_ssl = true
http.ssl_version = :SSLv3
http.start { ... }

The same trick also works with the net-http-persistent gem:

http =
http.ssl_version = :SSLv3

  1. Always using SSLv3 is not a general-purpose solution. For best security, you want to stick with Ruby’s default, which is to try TLSv1 before falling back to older versions. Unfortunately, this particular SSL-Tomcat bug breaks the normal automatic fallback. Use this explicit SSLv3 workaround only after you’ve explored other options for fixing the issue on the Tomcat side. 

Share this? Copy link

Feedback? Email me!

Hi! 👋 I’m Matt Brictson, a software engineer in San Francisco. This site is my excuse to practice UI design, fuss over CSS, and share my interest in open source. I blog about Rails, design patterns, and other development topics.

Recent articles

View all posts →

Open source projects


Generate your next Rails app interactively!

Updated 24 hours ago


A friendly CLI for deploying Rails apps ✨

Updated 1 day ago

More on GitHub →