How to troubleshoot RubyGems and Bundler TLS / SSL

Tram Ho

If you’re having problems with your SSL certificate and (or) the TLS version, you’ve come to the right place. In this guide, we’ll explain the causes of both of those problems and how to fix them. Many of the instructions in this article can help troubleshoot SSL certificate issues or TLS version issues. If you don’t mind the reason and just want to fix everything as quickly as possible, you can jump straight to solutions for SSL problems .

1. The problem

1.1 Why do I see the certificate verify failed error?

When you pull updates from RubyGems using gem update or gem install <your_gem> , … and get the following error:

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed .

This error occurs when your computer is missing a file that it needs to verify that the server behind is correct.

The latest version of RubyGems will fix this issue, so we recommend updating to current version. To have RubyGems update itself to the latest version, run gem update --system . If that doesn’t work, try the manual update procedure below.

What does the “should fix this” update mean for us? Review What Are These Certifications? and the sections below How does Ruby use CA certificates? to better understand the basics.

1.1.1 What are these certificates?

Whenever your computer communicates with the server (server) using HTTPS, it will use the SSL certificate as part of that connection. The certificate lets your computer know that it is communicating with the real server for a domain and ensures that the communication between your computer and the server is completely private without any problems. Any other computer knows what to send back and forth.

To see if the certificate for is correct, your computer references another certificate from the Certificate Authority (CA). The CA certificate package includes certificates from every company that offers SSL certificates for servers, like Verisign, Globalsign, and many others.

Each CA has a “root” certificate that is used to verify other certificates. CA certificates are called “root” because they sign other certificates (which can also sign other certificates). In other words, the diagram of the certificates will look like a tree, with the “root” certificates at the root of the tree.

Your computer will use the built-in CA package of multiple “root” certificates to know whether to trust an SSL certificate provided by a particular website, such as .

Occasionally, new companies are added to the CA bundle, or existing companies have certificates that expire and need to distribute new certificates. For most websites, this isn’t a big deal, because web browsers regularly update their CA bundles as part of general browser updates.

1.1.2 How Ruby uses CA certificates

The SSL certificate used by is derived from the new root certificate. Ruby (and therefore RubyGems and Bundler) doesn’t have a CA bundle that is regularly updated for use when interacting with websites. Usually, Ruby uses a CA package provided by the operating system (OS). On older operating systems, this CA bundle can really get old – as in a decade. When an old CA bundle fails to verify (new-ish) the certificate for , you may see an error in the question: certificate verify failed .

Things get further complicated when another unrelated change 18-24 months ago resulted in a new SSL certificate being issued to . This means the “roor” certificate is needed to verify connections have changed. So even if you previously upgraded RubyGems / Bundler to fix the SSL issue, you’ll need to upgrade again – this time to a newer version with newer certificates.

1.1.3 Troubleshooting Certificate Errors

Start by running an automated SSL check and follow the instructions. You might need to update Bundler, update RubyGems, manually update RubyGems certificate, or maybe even install a new OS certificate.

1.2 Why do I see read server hello A?

This error means your machine is unable to establish a secure connection to . The most common cause for that problem is a Ruby using an older version of OpenSSL. OpenSSL 1.0.1, released March 12, 2012, is the minimum version required to connect to , starting January 1, 2018.

To understand why that version is needed, keep reading. For instructions on how to update OpenSSL and / or Ruby to fix the problem, go to the troubleshooting section.

1.2.1 Protocol versions SSL and TLS

Secure connections on the internet use HTTPS, the secure version of HTTP. That security was originally provided by SSL, which stood for Secure Sockets Layer. Over time, researchers discovered vulnerabilities in SSL, and network developers responded with changes and fixes. After SSL 3.0, it was replaced with TLS, or Transport Layer Security .

Over time, the TLS has also been revised. TLS version 1.2, originally defined in 2011 and supported by OpenSSL starting in 2012, is the current standard. In 2017, any versions of SSL and TLS older than TLS 1.2 were found to have critical vulnerabilities that could be exploited by a known or knowledgeable adversary. Therefore, best practices suggest proactively blocking all SSL versions, as well as TLS versions 1.0 and 1.1.

1.2.2 TLS 1.0 and 1.1 are deprecated uses a 3rd party CDN provider called Fastly , which allows users around the world to download gems really quickly.

Last year, Fastly announced that it would stop using TLS 1.0 and 1.1 versions due to the authorization announced by the PCI Security Standards Council. ( Read more about this in Fastly’s blog post .)

Hence, will require at least TLSv1.2 starting January 2018. This means that and gem will no longer support Ruby and OpenSSL versions that do not support TLS 1.2.

1.2.3 Troubleshooting protocol errors

To fix the protocol connection error, start by running an automatic SSL test and following the instructions. You may need to update your Bundler, update RubyGems, or even reinstall Ruby (you can find instructions for reinstalling using a version manager or package manager.)

2. Solution

2.1 Automatic SSL Check

First, run this script to check if your error is caused by an SSL certificate issue or a TLS version issue.

You can run the script immediately using this command (including Windows 10):

If the output says “Your Ruby can’t connect to because you are missing the certificate” then you have a certificate verification error and need to update your certificate.

Instead, if you see the message “Your Ruby can’t connect to because your version of OpenSSL is too old” then your OpenSSL version is old and not compatible with TLSv1.2 and you need to upgrade. OpenSSL and / or recompile Ruby to use a newer version of SSL.

The instructions in this article can help you fix both problems.

2.2 Update bundle

Update to the latest Bundler version by running the command:

2.3 Update RubyGems

You can upgrade RubyGems with the self-update command:

If the above command fails, you can try to manually download the latest RubyGems and install it using following steps. In this example, we will download and install RubyGems 2.7.6. If the latest version of RubyGems has changed by the time you are reading this article, you will need to change wherever you see 2.7.6 to the version RubyGems you downloaded.

  • Step 1: Using your web browser, go to the Download RubyGems page and download the gems version of the latest rubygems.
  • Step 2: Once you’ve downloaded the gem, open on macOS or Command Prompt with Ruby on Windows.
  • Step 3: Change the folder to your Downloads folder. On macOS, the command will be cd ~/Downloads . On Windows, it will be cd C:Users%USERNAME%Downloads .
  • Step 4: Install gems to upgrade the downloaded RubyGems by running gem install --local rubygems-update-2.7.6.gem . Run the update_rubygems update command.

It’s done! Run gem --version to verify that you are on the latest version of RubyGems.

2.4 Updating System Clock

If your system clock is set to past or future time, your machine will not be able to establish a secure connection to . To solve the problem, you will need to set your system clock to the current time. In Linux, you can update the system clock by running sudo ntpdate .

Here are other possible solutions to update the system clock:

2.5 Update the CA certificate

2.5.1 Install a new RubyGems certificate

If you can’t update RubyGems, you can manually add a RubyGems certificate. If you have a new enough version of RubyGems (version 2.1.x or higher) you can use those “provided” certificates – and when the certificate is installed successfully it will work without lifting. RubyGems version level.

Warning: These instructions will only add a new certificate; Ruby will be preserved. To make sure your Ruby version can use TLSv1.2, run the code again. If not, follow the other set of instructions in this tutorial to upgrade Ruby.

Step 1: Get a new trusted certificate

Download the .pem file from this link: GlobalSignRootCA.pem

Then find the downloaded file and check to make sure the filename ends with .pem. ( Note : Some browsers will change the extension to .txt, which will prevent this from working. So it’s important to make sure the file you downloaded ends up with a .pem extension. )

Step 2: Locate the RubyGems certificate folder in your installation

Next, you’ll want to find the directory where you installed Ruby to add the .pem file to it.

On Windows, open your command line and type:

C:>gem which rubygems

You should see output like this:


To open a window showing the folder we are looking for, type the path up to the file extension in the same window (but use a backslash instead). For example, based on the output above, you would run this command:

C:>start C:Ruby21libruby2.1.0rubygems

This will open an Explorer window, showing the RubyGems folder it is installed in.

On macOS, open Terminal and run this command:

$ gem which rubygems

You should see output like this:


To open a window showing the directory we are looking for, use the open command on that output with no “.rb” at the end, like so:

$ open /opt/rubies/2.4.1/lib/ruby/2.4.0/rubygems

A Finder window will open showing the folder where RubyGems is installed.

Step 3: Copy a new trusted certificate

In the window, open the ssl_certs folder and drag your .pem file into it. It will be listed with other files like AddTrustExternalCARoot.pem.

Once you’ve done this, you can follow the instructions above to automatically update RubyGems. Visit the RubyGems Updates section for step-by-step instructions. If that doesn’t work, continue to follow this guide.

2.5.2 Install a new operating system certificate

This solution might work when the version of OpenSSL installed using Homebrew hinders Ruby’s ability to find the correct certificate. Sometimes, uninstalling everything and starting over is enough to fix everything.

First you will need to remove RVM. You can do that by running this command:

Next, you will need to remove OpenSSL from Homebrew. (Using --force sure you delete all OpenSSL versions you might have):

You can now reinstall RVM, following the instructions below.

2.5.3 Reinstall Ruby from the version manager

Install with rvm

Note: Try this solution if updating SSL certificate with RVM doesn’t work. If Ruby installed using RVM can’t find the correct certificates even though they were up to date, you can fix it by reinstalling RVM and then reinstalling your version of Ruby.

Run the following commands to remove RVM and reinstall it:

Then reinstall Ruby while telling RVM that you don’t want to use pre-compiled binaries. (Unfortunately, this process will take longer, but hopefully it will fix the SSL issue.)

This command will install Ruby 2.2.3. Adjust the command to install the Ruby version (s) you need:

Install using ruby-build or rbenv install

Follow the instructions outlined in rbenv’s Update and Troubleshooting guide .

2.5.4 Reinstall Ruby from the operating system package manager

macOS: Ruby built in

macOS 10.13 High Sierra comes with Ruby by default which is compatible with TLSv1.2.

To check your current macOS version, go to the Apple menu and select “About This Mac”. If you see anything other than “macOS High Sierra” you will need to upgrade to the latest macOS (or if not, install a newer version of Ruby with Homebrew by following the next set of instructions. after these).

To upgrade to High Sierra:

  1. Open the App Store app
  2. Select the tab “Update”
  3. Click the “Install” button for “macOS High Sierra”

macOS: Installed using Homebrew

Note: To install a newer version of Ruby with Homebrew, first make sure that Homebrew is installed. If the brew command doesn’t appear, follow the installation instructions at and then go back to these steps.

Run brew update Run brew install ruby If Ruby is already installed, run brew upgrade ruby to upgrade to the latest version.

Debian or Ubuntu 16.04: Installed using apt-get

Note: To remove Ruby using apt, you need to check which Ruby version you have installed. apt install Ruby v2.3.1.

To uninstall, follow the instructions listed here. (These instructions work for both Ubuntu and Debian.)

Once you’ve successfully uninstalled Ruby, reinstall it by running:

Fedora: Installed using dnf

Note: The latest versions of Fedora use dnf as its package manager, but older versions use yum instead. If you see the error message dnf : command not found, replace dnf in these instructions with yum .

First, uninstall Ruby by running:

And then reinstall (this command will install Ruby 2.3):

RHEL or CentOS: Installed with yum

Follow these instructions to upgrade Ruby on CentOS . (They also include instructions for troubleshooting OpenSSL.)

Windows: Installed using Ruby Installer

From the Control Panel, find the Ruby installer in “Programs”. Click the folder and click “Uninstall Ruby” again. Reinstall by downloading Ruby and Ruby DevKit at RubyInstaller.

Additional help

Run another automatic SSL check

Rerun the automatic SSL test to verify if the problem is an SSL issue or a TLS problem. If you’ve followed the troubleshooting steps above and still have the problem, go to the troubleshooting section below for the next steps.

Create a problem

If none of these instructions fixed the problem, the next step is to open the problem.

(Create issue in RubyGems crash tracker if your error came from gem install . If error is caused by bundle install cause then create issue in Bundler issue tracker

Please include: – Output when running gem env : – Output when running bundle env : – Output when running ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION' : – Manager of your Ruby ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION' (if Yes): – Your operating system and OS version: – Your package manager name and version (if applicable):

Contribute to this article

If you find a solution not listed here, please submit a PR to add your solution to this guide or leave it in the comments below! I wish you a good day


The article was translated from the source How to troubleshoot RubyGems and Bundler TLS / SSL Issues . (In the process of translating the article, there is any incorrect or unsatisfactory translation in the comments section below)

Share the news now

Source : Viblo