EC
OpenSSL::SSL::SSLError
RubyERRORNotableNetwork

TLS/SSL handshake or certificate failure

Quick Answer

Do not disable certificate verification in production; update CA certificates or pin the expected certificate.

What this means

Raised when an SSL/TLS operation fails — including certificate verification errors, handshake failures, protocol mismatches, and expired certificates. Requires the openssl gem (bundled with MRI Ruby).

Why it happens
  1. 1Server certificate is expired, self-signed, or for a different hostname
  2. 2Client and server cannot agree on a TLS protocol version or cipher suite
  3. 3System CA bundle is outdated

Fix

Update CA bundle or configure SSL context

Update CA bundle or configure SSL context
require 'net/http'
require 'openssl'

http = Net::HTTP.new('api.example.com', 443)
http.use_ssl = true
http.ssl_version = :TLSv1_2
http.ca_file = '/etc/ssl/certs/ca-certificates.crt'
http.verify_mode = OpenSSL::SSL::VERIFY_PEER   # never disable this in production

Why this works

Specifying an up-to-date CA bundle and requiring VERIFY_PEER ensures certificates are properly validated.

Code examples
Certificate verification failureruby
Net::HTTP.get(URI('https://expired.badssl.com/'))
# OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=error: certificate verify failed
NEVER do this in productionruby
# DANGEROUS — disables cert validation
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
Rescue SSL errorruby
begin
  response = http.get('/api')
rescue OpenSSL::SSL::SSLError => e
  raise TLSError, "SSL failure: #{e.message}"
end
Sources
Official documentation ↗

Ruby Standard Library Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Ruby errors