Requests SSLError: Fix Verify-Failed Behind Proxies

Your deploy log shows one line and your whole pipeline stops: requests.exceptions.SSLError: CERTIFICATE_VERIFY_FAILED. The URL works in your browser. curl passes from the same laptop. Yet Python refuses to connect, and the traceback offers no hint about which certificate it disliked or why. If you've hit this on office Wi-Fi the week before launch, you know the frustration.

The confusion comes from how many trust stores one laptop holds. Browsers use the OS store, curl often uses another, and Python's Requests uses certifi's bundled roots unless you tell it otherwise. A corporate proxy that re-signs traffic, an expired leaf, or a server that forgot its intermediate cert each breaks a different link of the same chain — but all surface as the identical SSLError.

This guide gives you a repeatable way out. You'll learn what the verify-failed message really asserts, how to classify expired versus self-signed versus incomplete-chain failures in seconds, where certifi and REQUESTS_CA_BUNDLE fit, why verify=False is never the answer, and what makes macOS special. By the end you'll diagnose any Requests SSLError in minutes instead of stabbing at reinstalls.

What CERTIFICATE_VERIFY_FAILED Actually Means

When Requests raises CERTIFICATE_VERIFY_FAILED, it's reporting one specific failed assertion: OpenSSL could not build an unbroken signature path from the server's leaf certificate up to a root certificate in the bundle it was given. The handshake itself worked — bytes flowed, the server presented its cert. What failed was the trust decision afterward. That distinction matters because it tells you the network is fine and the cryptography is fine; only the trust inputs are wrong.

Those inputs are small: the chain the server sent, the hostname you requested, the current time, and the set of roots you trust. Requests assembles the trust set from the verify argument first, then REQUESTS_CA_BUNDLE, then CURL_CA_BUNDLE, then certifi's bundled PEM. OpenSSL walks the chain link by link, checking signatures, dates, and the hostname, and the first broken link becomes the message you see.

So your first move is evidence, not action. Run the trust-store snippet and note exactly which bundle your interpreter resolves. Then reproduce with openssl s_client and read its Verify return code. Only when you can name the broken link — wrong bundle, expired leaf, unknown root, missing intermediate — should you change anything. That discipline turns a scary TLS error into a ten-minute lookup.

import os
import ssl

import certifi

print("certifi bundle:", certifi.where())
print("openssl defaults:", ssl.get_default_verify_paths())
for var in ("REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE", "SSL_CERT_FILE"):
    print(var, "=", os.environ.get(var, "(not set)"))
ctx = ssl.create_default_context()
print("default verify mode:", ctx.verify_mode)
print("check_hostname:", ctx.check_hostname)

Expired vs Self-Signed vs Incomplete Chain

Three failures share one exception name, and mixing them up wastes hours. An expired leaf means the server's own dates lapsed — the chain is structurally fine but time has run out. A self-signed certificate means no trusted root signed it at all, so there's no path to build no matter how fresh the bundle is. An incomplete chain means the server forgot to send its intermediate certificates, so OpenSSL sees the leaf floating with a gap between it and a root it actually trusts.

Each has a signature. Expired names itself plainly and openssl shows notAfter in the past. Self-signed shows issuer identical to subject, and s_client reports self-signed certificate. Missing intermediates produce unable to get local issuer certificate or error codes 20/21, and -showcerts reveals only one certificate where two or three should appear.

The fixes don't transfer. Renewal is the server owner's job and no client bundle edit helps. Self-signed needs the private root installed on the client. A missing intermediate needs the server to send its full chain — though you can bandage it client-side with a bundle containing the intermediate. The classifier snippet trains your eye: paste the message, get the category, then apply only that category's fix.

SAMPLES = {
    "certificate has expired": "expired leaf",
    "self-signed certificate": "self-signed",
    "unable to get local issuer certificate": "incomplete chain",
}


def classify(message):
    low = message.lower()
    for marker, kind in SAMPLES.items():
        if marker in low:
            return kind
    return "unknown"


tests = [
    ("ssl.SSLCertVerificationError: certificate has expired", "expired leaf"),
    ("[SSL: CERTIFICATE_VERIFY_FAILED] self-signed certificate", "self-signed"),
    ("unable to get local issuer certificate", "incomplete chain"),
]
for msg, want in tests:
    got = classify(msg)
    assert got == want, (msg, got)
    print(f"{got:>16} <= {msg[:60]}")
print("classifier ok")

Corporate MITM Proxies: Why Office Wi-Fi Breaks Everything

Corporate proxies break TLS on purpose. To scan traffic, the proxy terminates your session, inspects the plaintext, then opens its own session to the real server — re-signing everything with a company root your laptop was given on hiring day. Browsers trust it because IT pushed the root into the OS store. Python doesn't, because Requests reads certifi's public bundle, which has never heard of your company's root.

The tell is environmental: failures follow the network, not the code. Office Wi-Fi and VPN fail while hotspots pass, and env shows HTTPS_PROXY set. The proxy isn't broken and the target server isn't broken — your client simply lacks one root certificate.

The durable fix has two halves. Get the corporate root CA (usually a .crt or .pem from IT or the OS store), append it to a copy of certifi's bundle, and export REQUESTS_CA_BUNDLE to that file wherever the app runs — laptop shells, CI environments, and container images. The snippet shows the resolution pattern: explicit bundle wins, environment provides it, and the session proves the path before any byte hits the wire. Do it once per environment and the whole class of failures vanishes. Log the resolved bundle path at startup so the next proxy rotation shows up as a one-line diff instead of another morning-long mystery.

import os

import certifi
import requests

bundle = os.environ.get("REQUESTS_CA_BUNDLE", certifi.where())
s = requests.Session()
s.verify = bundle
print("session verify resolves to:", s.verify)
assert isinstance(s.verify, str) and s.verify.endswith(".pem")
req = requests.Request("GET", "https://internal.example.com/api/health")
prepped = s.prepare_request(req)
print("prepared:", prepped.method, prepped.url)
print("https proxy:", os.environ.get("HTTPS_PROXY", "(none)"))
print("ok - trust path resolved, no request sent")

Why verify=False Is Never the Fix

When nothing else works, verify=False always does — and that's exactly what makes it dangerous. It doesn't fix trust; it deletes the trust question. Hostname checks go away, chain checks go away, expiry checks go away. Your code will happily accept a cert for the wrong host, signed by nobody, relayed by an attacker running a hotspot named after your office. Tokens, cookies, and payloads all flow through a channel you chose not to authenticate.

The snippet proves both halves against a real local TLS server with a self-signed cert. With verify=False the request succeeds but Python fires InsecureRequestWarning — the library itself telling you the channel is unauthenticated. With default verification the same request raises SSLError, which is the protection working as designed. Read those two outcomes together: the error you wanted to silence was the guard doing its job.

There's also a shelf-life trap. verify=False committed during a late-night debug becomes permanent because nothing forces a revisit — until a scanner flags it or an attacker exploits it. The safe replacement is narrow: verify="/path/to/internal-ca.pem" for the one host that needs it, or a merged bundle via REQUESTS_CA_BUNDLE. Add grep -rn verify=False to CI so the bypass can never ship quietly again.

import shutil
import socket
import ssl
import subprocess
import tempfile
import threading
import warnings
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

import urllib3
import requests


class H(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b"{\"ok\": true}"
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *a):
        pass


tmp = tempfile.mkdtemp()
key, crt = tmp + "/k.pem", tmp + "/c.pem"
subprocess.run([shutil.which("openssl"), "req", "-x509", "-newkey",
                "rsa:2048", "-keyout", key, "-out", crt, "-days", "1",
                "-nodes", "-subj", "/CN=127.0.0.1"],
               check=True, capture_output=True)
srv = ThreadingHTTPServer(("127.0.0.1", 0), H)
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ctx.load_cert_chain(crt, key)
srv.socket = ctx.wrap_socket(srv.socket, server_side=True)
port = srv.server_address[1]
threading.Thread(target=srv.serve_forever, daemon=True).start()
url = f"https://127.0.0.1:{port}/"
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    r = requests.get(url, verify=False, timeout=10)
    print("verify=False status:", r.status_code, r.text)
bad = [w for w in caught
       if issubclass(w.category, urllib3.exceptions.InsecureRequestWarning)]
print("InsecureRequestWarning fired:", bool(bad))
assert bad, "expected InsecureRequestWarning"
try:
    requests.get(url, timeout=10)
except requests.exceptions.SSLError as e:
    print("default verify still refuses self-signed:", str(e)[:80])
srv.shutdown()
srv.server_close()

macOS Trust Store Quirks and the Fix

macOS adds a twist that confuses even experienced engineers: python.org installers ship their own CA bundle and their own OpenSSL, ignoring the Keychain entirely. Safari can trust a site — because Safari reads the Keychain — while the same Mac's Python raises CERTIFICATE_VERIFY_FAILED for the same URL. Neither side is wrong; they're reading different books of trusted roots.

The tell is the split: Keychain shows the root as trusted, Safari loads the page, but python -c "import requests" fails. Confirm by printing ssl.get_default_verify_paths() and certifi.where() — you'll see paths under /Library/Frameworks/Python.framework, nowhere near the Keychain. Homebrew Python behaves differently since it links system OpenSSL, which is why the same script can pass under brew Python and fail under a python.org install on one machine.

The fix matches the install. For python.org builds, run the Install Certificates.command bundled with your version (under /Applications/Python 3.x) to refresh the private bundle. For managed fleets, prefer exporting REQUESTS_CA_BUNDLE to a controlled PEM so every interpreter — python.org, brew, or venv — resolves the same roots. Either way, re-test inside the failing interpreter, not just the browser, because the browser was never the authority here.

Reproducing and Reading the Error on Purpose

The fastest way to stop fearing an error is to raise it on purpose in a scratch file. Python's ssl module exposes SSLCertVerificationError with structured fields — verify_code and verify_message — that carry more signal than the str() form most tracebacks show. Building one deliberately teaches your hands the handling pattern: catch the narrow type, log the structured fields, and branch on the code instead of matching message text.

That last point deserves emphasis because message-text matching is brittle across OpenSSL versions. The human-readable prefix changes between releases ("self signed" versus "self-signed", extra bracketed codes), but the numeric verify codes are stable: 10 for expired, 18 for self-signed, 20 and 21 for chain gaps. Code that branches on verify_code survives upgrades; code that greps strings breaks on the next interpreter bump.

Use the snippet as a template for your error-handling drills. Raise it, catch it, print the fields, then re-raise so the drill mirrors production behavior where the error must propagate to your retry or alerting layer. Once catching the real type feels routine, live tracebacks stop looking like walls of red and start reading like lab reports with the conclusion highlighted.

import shutil
import socket
import ssl
import subprocess
import tempfile
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class H(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b"ok"
        self.send_response(200)
        self.send_header("Content-Length", "2")
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *a):
        pass


tmp = tempfile.mkdtemp()
key, crt = tmp + "/k.pem", tmp + "/c.pem"
subprocess.run(
    [shutil.which("openssl"), "req", "-x509", "-newkey", "rsa:2048",
     "-keyout", key, "-out", crt, "-days", "1", "-nodes",
     "-subj", "/CN=127.0.0.1"],
    check=True, capture_output=True,
)
srv = ThreadingHTTPServer(("127.0.0.1", 0), H)
srv_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
srv_ctx.load_cert_chain(crt, key)
srv.socket = srv_ctx.wrap_socket(srv.socket, server_side=True)
port = srv.server_address[1]
threading.Thread(target=srv.serve_forever, daemon=True).start()
try:
    raw = socket.create_connection(("127.0.0.1", port), timeout=10)
    ctx = ssl.create_default_context()
    tls = ctx.wrap_socket(raw, server_hostname="127.0.0.1")
    tls.close()
    print("UNEXPECTED: self-signed cert verified")
except ssl.SSLCertVerificationError as e:
    print("caught advertised error:", type(e).__name__)
    print("verify_code:", e.verify_code, "message:", e.verify_message)
    assert e.verify_code == 18
    raise
finally:
    srv.shutdown()
    srv.server_close()