OpenSSL::SSL::SSLError: certificate verify failed in Ruby Net::HTTP requests

Explanation

The error OpenSSL::SSL::SSLError: certificate verify failed occurs when Ruby’s OpenSSL cannot locate a trusted CA bundle. In minimal containers the default store (/etc/ssl/certs) may be empty, while a full host usually provides it.

Confirmed facts

• Ruby’s OpenSSL reads ENV['SSL_CERT_FILE'] (or SSL_CERT_DIR) on the first SSL connection; after that the value cannot be changed.
• Setting the variable early in the boot process makes Net::HTTP and any subsequently loaded gems use the specified bundle.

Recommended steps

1. Add a trusted CA bundle to the image (e.g., the file provided by the certifi gem or a copy of Mozilla’s certdata.txt).
2. Before requiring net/http or any gem that may trigger an TLS handshake, set ENV['SSL_CERT_FILE'] = '/path/to/bundle.pem' (for example in an initializer or via Dockerfile ENV).
3. If the container already contains the ca-certificates package and the default store is populated, you can omit this step and rely on the system store.

Runtime detection and fallback

At startup you can test whether a usable store exists:

require 'openssl'
store = OpenSSL::X509::Store.new
store.set_default_paths
if store.path.nil? || store.num_entries.zero?
  # bundle missing – point to bundled file
  ENV['SSL_CERT_FILE'] = '/app/certs/ca-bundle.pem'
end

If you prefer to handle the error lazily, rescue OpenSSL::SSL::SSLError, create a temporary store with the bundled certs, and retry the request using a custom Net::HTTP instance with cert_store set to that store.

Verification

• Run ruby -ropenssl -e 'puts OpenSSL::X509::Store.new.set_default_paths.to_h' and confirm the returned ca_file matches the bundled path.
• Make a test HTTPS request (e.g., to https://www.google.com) and ensure no SSLError is raised.
• Load another gem that uses OpenSSL (such as pg or aws-sdk-s3) and verify it can establish TLS connections without errors.

Missing diagnostic detail

Does the container image already include the ca-certificates package (i.e., is /etc/ssl/certs populated)? If yes, you may rely on the default store and setting SSL_CERT_FILE is unnecessary; if not, bundling a CA file and setting the variable is required.