Fix RubyGems SSL Certificate Verification Errors on macOS

You will learn what an SSL/TLS certificate verification error means, why RubyGems needs a current trusted certificate-authority (CA) bundle, and how to repair the trust configuration instead of bypassing HTTPS. You will also learn how to inspect and remove insecure duplicate gem sources.

RubyGems downloads package metadata and gem files from https://rubygems.org. The https part is important: it encrypts the connection and verifies that the server is really the server RubyGems intended to contact.

For verification to succeed, Ruby needs access to trusted certificate authority (CA) certificates. A CA is an organization whose certificate can establish trust in certificates presented by websites. RubyGems checks the certificate chain presented by RubyGems and its download host against that local list of trusted CAs.

A message such as:

certificate verify failed

usually means one of these is true:

• The operating system or Ruby CA bundle is old and does not trust a required CA.
• Ruby is configured to use a missing or incorrect CA file.
• The machine clock is wrong, making certificates appear expired or not yet valid.
• A proxy, antivirus tool, or corporate network is intercepting HTTPS with its own certificate.

Adding http://rubygems.org does not solve the certificate problem. It merely gives RubyGems an unencrypted source it can use when HTTPS fails. HTTP allows a network attacker to alter package metadata or downloads, so it should not be used for installing dependencies.

The correct fix is to update or correctly configure the CA certificates, then keep only the HTTPS source.

Think of HTTPS like receiving a sealed package from a known supplier.

• Encryption is the seal: outsiders cannot read or alter the package easily.
• The server certificate is the supplier's identification card.
• The CA bundle is your trusted list of organizations allowed to confirm that identification card.

If your trusted list is outdated, you may reject a legitimate package. Switching from HTTPS to HTTP is like accepting an unsealed package because you cannot check the identification card. Updating the trusted list lets you verify the supplier while keeping the package sealed.

RubyGems lets you view, add, and remove package sources.

gem sources --list

A secure configuration should normally include only:

https://rubygems.org/

Remove an insecure HTTP source:

gem sources --remove http://rubygems.org/

If RubyGems has an older default URL without a trailing slash, list sources first and remove the exact value shown:

gem sources --remove http://rubygems.org

Then verify the result and retry the installation:

gem sources --list
gem install rails -v 3.2.14

On an RVM-managed Ruby installation, RVM has historically provided a command for refreshing SSL certificates:

rvm osx-ssl-certs update all

After updating certificates, open a new terminal or reload RVM if necessary, then retry RubyGems over HTTPS.

If Ruby was built with a CA bundle that is not found automatically, Ruby/OpenSSL can be pointed to a PEM CA bundle with SSL_CERT_FILE:

export SSL_CERT_FILE="/path/to/cacert.pem"
gem install rails -v 3.2.14

Use a maintained, trusted CA bundle. Do not download a certificate file from an unverified source.

Consider this sequence:

gem sources --list
gem sources --remove http://rubygems.org/
rvm osx-ssl-certs update all
gem install rails -v 3.2.14

1. gem sources --list prints every registry RubyGems will query. If both HTTP and HTTPS are present, RubyGems may try both.
2. gem sources --remove ... removes the unencrypted HTTP registry. This prevents RubyGems from silently falling back to an insecure connection.
3. rvm osx-ssl-certs update all refreshes certificate files used by RVM Rubies on macOS, when that RVM command is available.
4. gem install contacts https://rubygems.org.
5. Ruby receives the server's certificate chain and compares it with the trusted CAs it can access.
6. With a current and correctly located CA bundle, verification succeeds, RubyGems downloads the metadata, resolves rails version 3.2.14, and installs it.

If step 6 still fails, check the system date and inspect whether a network proxy is replacing the server certificate. Updating a CA bundle cannot fix an incorrect clock or an untrusted corporate interception certificate.

Certificate verification affects far more than RubyGems:

• Application setup: bundle install downloads all dependencies through RubyGems sources.
• CI pipelines: a build server must trust HTTPS certificates before it can install dependencies reliably.
• API clients: Ruby applications using Net::HTTP, Faraday, or HTTParty verify API server certificates.
• Internal package registries: a company may host gems on an internal HTTPS registry with a certificate issued by its own CA.
• Containers: minimal container images may not include CA certificates until a CA package is installed.
• Corporate networks: a TLS-inspecting proxy may require its organization CA certificate to be trusted by the system and language runtime.

In each case, the safe response is to establish a valid trust chain, not to disable verification or change the URL to HTTP.

In real Ruby projects, developers normally keep the package source in the Gemfile explicitly on HTTPS:

source "https://rubygems.org"

gem "rails", "3.2.14"

They then install from the project directory:

bundle install

Common secure practices include:

• One canonical source: Use https://rubygems.org unless the project intentionally uses a documented private registry.
• Locked dependencies: Commit Gemfile.lock so developers and CI resolve the same dependency versions.
• Current tooling: Keep RubyGems, Bundler, Ruby, and operating-system CA certificates maintained where project compatibility permits.
• Environment-specific CA configuration: In a controlled corporate environment, configure the corporate root CA through the operating system, container image, or SSL_CERT_FILE rather than disabling TLS verification in code.
• Early diagnostics: Check date, gem sources --list, and proxy environment variables such as HTTPS_PROXY before changing package sources.

For a legacy tutorial that requires Rails 3.2, use an isolated Ruby version manager environment. The SSL fix remains the same: trust HTTPS correctly.

Adding HTTP as a permanent workaround

gem sources -a http://rubygems.org

This may make an installation appear to work, but it weakens dependency security. Remove the HTTP source after repairing certificate trust.

Disabling certificate verification

Some commands, scripts, or environment settings can bypass verification. Avoid this except for tightly controlled temporary diagnostics. It removes the protection that detects an impostor or modified download.

Assuming the error means the gem does not exist

The message begins with “Could not find a valid gem,” but the detailed reason says the metadata download failed. Read the final lines: certificate verify failed identifies a connection-trust issue, not a missing Rails version.

Updating the wrong Ruby installation

With RVM, rbenv, system Ruby, and multiple terminals, gem may not belong to the Ruby you think it does.

which ruby
which gem
ruby -v
gem env home

Run certificate and RubyGems maintenance commands for the Ruby that actually runs gem.

Ignoring an incorrect computer clock

Certificates have validity dates. Check the date before making large configuration changes:

date

Hard-coding an unavailable CA file

This can break all HTTPS requests:

export SSL_CERT_FILE="/does/not/exist/cacert.pem"

Only set SSL_CERT_FILE when you know the file exists, is readable, and contains a maintained CA bundle.

Using sudo with a version-managed Ruby

RVM gemsets are usually per-user. Running sudo gem ... can invoke a different system Ruby and install gems outside the intended gemset. Prefer gem install ... without sudo when using RVM.

RubyGems source configuration and certificate trust are related but different:

• A source URL tells RubyGems where to download packages.
• A CA bundle tells Ruby whether the HTTPS server at that URL is trustworthy.

# See RubyGems sources
gem sources --list

# Remove an insecure source (use the exact URL shown by --list)
gem sources --remove http://rubygems.org/

# Refresh RVM macOS certificates, if supported by the installed RVM version
rvm osx-ssl-certs update all

# Check which Ruby and gem command are active
which ruby
which gem
ruby -v
gem env

# Check the machine clock
date

# Retry using HTTPS
gem install rails -v 3.2.14

Key rules:

• Keep https://rubygems.org/ as the RubyGems source.
• Do not treat HTTP as a permanent fallback for dependency installation.
• certificate verify failed usually indicates CA trust, clock, proxy, or runtime configuration trouble.
• With RVM, avoid sudo gem install; it can use a different Ruby.
• Set SSL_CERT_FILE only to a real, trusted PEM CA bundle.

Why does RubyGems say it cannot find a gem when the real issue is SSL?

RubyGems must download repository metadata before it can determine which gem versions exist. If the HTTPS request fails, it cannot look up the version, so it reports both the lookup failure and the underlying SSL reason.

Is http://rubygems.org safe to use?

No. HTTP does not provide the authentication and integrity checks supplied by HTTPS. Remove it and fix certificate trust instead.

Does SSLv3 in the error mean that I should enable SSLv3?

No. In older OpenSSL error output, SSLv3 read server certificate can describe an internal handshake state. It is not a recommendation to enable the obsolete SSLv3 protocol.

Why does the error mention an Amazon S3 URL?

RubyGems may use a storage or delivery host for repository metadata and gem files. Ruby still verifies the HTTPS certificate for the host it actually connects to.

How do I know whether RVM is using the correct Ruby?

Run which ruby, which gem, ruby -v, and gem env home. Their paths should point to the RVM Ruby and gemset you expect.

What if updating CA certificates does not fix the problem?

Check that the system clock is correct, inspect proxy settings, and ask your network administrator whether HTTPS traffic is intercepted by a corporate certificate. That CA must be trusted by the environment running Ruby.

Should I upgrade RubyGems or Ruby?

If the legacy project supports it, updating RubyGems and using a supported Ruby can improve compatibility with current TLS and certificate infrastructure. However, keep project version constraints in mind and do not use an upgrade as a substitute for properly configured CA certificates.

• HTTPS and TLS — The protocol RubyGems uses to encrypt downloads and authenticate servers.
• Certificate authorities (CAs) — The trust anchors used to verify website certificates.
• OpenSSL in Ruby — Ruby's TLS library and a common source of certificate configuration issues.
• RubyGems sources — The registry URLs RubyGems queries for packages.
• Bundler and Gemfile — Project-level dependency management built on RubyGems.
• RVM gemsets — Isolated Ruby dependency environments that can affect which gem command runs.
• Environment variables — Variables such as SSL_CERT_FILE can configure certificate lookup paths.
• Proxy configuration — HTTPS proxies can affect which certificate a client receives.