A Python certificate verification failure means the TLS client could not establish that the certificate presented for a connection was valid and trusted for the requested hostname. Start with the full error message, the Python interpreter and client library in use, and the network path; then fix the clock, hostname, server certificate chain, or trusted CA configuration indicated by the evidence. For private infrastructure or an authorized inspection proxy, configure a CA bundle obtained from a trusted administrator rather than turning verification off. This guide provides reproducible diagnostics for standard-library HTTPS, requests, and pip, including how to confirm the repair.
First response and diagnostic scope
When you see [SSL: CERTIFICATE_VERIFY_FAILED], preserve the complete exception, especially the text after certificate verify failed. An expired certificate, hostname mismatch, and missing issuer may produce the same broad exception but require different repairs. Check the machine's date, time, and timezone; confirm that the URL uses the intended hostname; and identify whether the failure occurs in urllib, requests, pip, or another client.
Reproduce the failure with the same interpreter, environment, URL, and network path as the application. For an HTTPS blockchain RPC endpoint, do not paste an API key or complete credential-bearing URL into logs or support tickets. This article covers server certificate verification; client certificate authentication is a separate configuration issue.
A browser succeeding does not prove Python will succeed: the browser and Python client may use different trust stores, proxy settings, or cached intermediates. Conversely, a successful TLS connection only establishes an authenticated encrypted channel; it does not prove that an RPC method or application credential is correct.
- Record the exact hostname, exception detail, client library, Python version, operating system or container, and whether a proxy is involved.
- If only one service fails, investigate its certificate and chain; if many unrelated services fail in the same environment, investigate local trust, time, and network interception.
- Keep verification enabled while diagnosing. Never treat
verify=Falseor a globally unverified SSL context as a production fix.
Prerequisites and environment inventory
Use a terminal in the environment that actually fails: a virtual environment, container, remote worker, or notebook kernel may not share the system Python's packages or certificates. The following standard-library script requires no network access. Run it with the interpreter that starts your application; on Windows, use the appropriate py launcher if necessary.
The default paths reported by ssl describe OpenSSL's default configuration, not necessarily the CA bundle used by every HTTP library. Environment variables can alter client behavior, and explicit application configuration can override defaults. Treat the output as a starting point rather than proof of which certificate verified a particular connection.
- Inspect proxy settings separately without printing credentials:
HTTPS_PROXY,HTTP_PROXY, andNO_PROXYmay affect the route. - For pip, run
python -m pip --versionwith the same interpreter. In a notebook, inspectsys.executableinside the kernel. - Paths, environment variables, and installed CA packages can differ between a host and its container or CI job.
import os
import ssl
import sys
print('Python executable:', sys.executable)
print('Python version:', sys.version)
print('OpenSSL:', ssl.OPENSSL_VERSION)
print('Default verify paths:', ssl.get_default_verify_paths())
for name in ('SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'PIP_CERT'):
print(f'{name}:', os.environ.get(name, '<unset>'))
try:
import requests
print('requests version:', requests.__version__)
print('requests default bundle:', requests.certs.where())
except ImportError:
print('requests is not installed in this interpreter')Certificate verification and trust stores
During a TLS handshake, the server presents a certificate and normally supplies intermediate certificates needed to build a chain to a trusted root certificate authority (CA). The client checks that chain, certificate validity periods, and the requested hostname. A failure can mean the server omitted an intermediate, the local trust bundle lacks the relevant root, or the presented certificate is not valid for the hostname.
A corporate TLS-inspection proxy can terminate and reissue HTTPS certificates using an organization-controlled CA. If the proxy is authorized, the Python client must trust the appropriate organization CA as well as any public roots needed for other destinations. Obtain the CA or approved bundle through your organization's authenticated distribution process; do not blindly trust a certificate downloaded from the connection that is failing.
Python's standard ssl module can load system or OpenSSL-configured defaults. Requests commonly uses a CA bundle supplied through its dependency configuration, often certifi, while pip's behavior depends on its version and Python version. Installing or importing certifi alone does not configure every client to use it. See the Python SSL documentation and Requests certificate verification documentation for the relevant client behavior.
Reproduction with the standard library
Set RPC_URL to the HTTPS URL that fails, then run this script using the affected interpreter. For a general web service, the same test works with its HTTPS URL. The script sends a GET request, so use an endpoint where that request is acceptable; it does not need a successful application response to test the TLS handshake. Avoid displaying or sharing the variable if it contains a key.
An HTTP error such as 401, 404, or 405 is reported separately below: it indicates that TLS completed and the server returned an HTTP response, not that the application request succeeded. A verification exception prints OpenSSL's verification message when available.
- Compare the result inside and outside the container or proxy only when policy allows; a difference narrows the investigation but does not identify the cause by itself.
- The standard library can honor proxy environment variables. A direct connection test and a proxied application request may reach different certificate presenters.
- Timeouts, DNS failures, and connection refusals are not certificate verification failures; troubleshoot those network issues separately.
import os
import ssl
import urllib.error
import urllib.request
url = os.environ['RPC_URL']
if not url.lower().startswith('https://'):
raise SystemExit('RPC_URL must use HTTPS')
try:
with urllib.request.urlopen(url, timeout=10) as response:
print('TLS succeeded; HTTP status:', response.status)
except urllib.error.HTTPError as exc:
print('TLS succeeded; HTTP error status:', exc.code)
except urllib.error.URLError as exc:
reason = exc.reason
if isinstance(reason, ssl.SSLCertVerificationError):
print('Certificate verification failed:', reason.verify_message)
else:
print('Connection failed:', type(reason).__name__, str(reason))Interpreting certificate failure details
Use the most specific message and your environment inventory to choose a repair. Error wording varies with Python and OpenSSL versions; an issuer error alone cannot distinguish an incomplete server chain from a missing client trust anchor or an inspecting proxy.
If you operate the service, inspect the leaf and intermediate certificates presented on the actual route, including SNI for the requested hostname. For example, openssl s_client -connect HOST:443 -servername HOST -showcerts displays certificates presented by a direct connection; replace HOST with the hostname, not a URL. This command does not automatically reproduce an HTTP proxy path, and displayed certificates are not by themselves proof of a trusted chain. Do not share sensitive connection details.
certificate has expiredornot yet valid: check the system clock and certificate validity dates; renew or replace an invalid server certificate.hostname mismatchor an IP address mismatch: use the intended DNS hostname, or have the server operator issue a certificate whose subject alternative names cover the address in use.unable to get local issuer certificateorself-signed certificate in certificate chain: investigate the served intermediates, client CA bundle, and authorized proxy before changing trust.- A private or self-signed deployment needs an explicitly trusted certificate or private CA, distributed and rotated through a controlled process.
CA bundle configuration for Python clients
Prefer repairing a public server's incomplete chain on the server and updating the affected environment's supported CA packages. For an authorized private CA or inspection proxy, obtain a PEM bundle from your administrator and verify its source before use. An explicit bundle can replace the client's usual roots rather than add to them, so supply an approved bundle containing all trust anchors required by that application's destinations. Trusting an additional root expands which issuers can authenticate those destinations; scope access and changes accordingly.
The following example loads an approved bundle into the standard-library default context and makes an HTTPS request. Set CA_BUNDLE to an absolute PEM file path and RPC_URL to the intended endpoint. Supplying cafile here uses that bundle instead of implicitly loading the default CA certificates; hostname verification remains enabled.
For Requests, the equivalent per-request setting is requests.get(url, verify='/path/to/approved-bundle.pem', timeout=10). A session can use session.verify for a scoped default. REQUESTS_CA_BUNDLE can configure Requests through the environment; standard OpenSSL-based defaults may instead use SSL_CERT_FILE. These variables are not interchangeable guarantees for every library, and explicit settings can take precedence. Consult the specific client's documentation.
import os
import ssl
import urllib.error
import urllib.request
url = os.environ['RPC_URL']
if not url.lower().startswith('https://'):
raise SystemExit('RPC_URL must use HTTPS')
context = ssl.create_default_context(cafile=os.environ['CA_BUNDLE'])
try:
with urllib.request.urlopen(url, context=context, timeout=10) as response:
print('TLS succeeded; HTTP status:', response.status)
except urllib.error.HTTPError as exc:
print('TLS succeeded; HTTP error status:', exc.code)
except urllib.error.URLError as exc:
print('Connection failed:', type(exc.reason).__name__, str(exc.reason))pip, operating systems, and isolated environments
If python -m pip install fails, first verify the interpreter, pip version, index hostname, proxy path, and clock. Pip supports a one-off CA bundle with python -m pip install --cert /path/to/approved-bundle.pem PACKAGE; replace both placeholders. Its PIP_CERT setting is another option. A bundle used for package installation must cover the package indexes and any other HTTPS hosts pip contacts.
Pip's certificate store behavior is version-dependent. According to the pip HTTPS certificate documentation, pip 24.2 and later on Python 3.10 or later uses system certificates in addition to certifi by default. Older combinations differ. Upgrade pip or CA packages through an already trusted channel when appropriate; an attempted upgrade cannot repair a download if that very download is blocked by the same trust failure.
For Python installed from python.org on macOS, the installation may include an Install Certificates.command for that specific Python version. Use the script supplied with the installation and review its behavior; it is not a universal fix for Homebrew, system, or container Python. On Linux and in containers, check the distribution's CA certificate package and update mechanism. On Windows, determine which store the actual client uses instead of assuming every Python library automatically uses the Windows trust store.
A virtual environment, conda environment, container image, or notebook kernel can have its own interpreter and trust configuration. Rebuild or update the environment in its normal deployment workflow, and restart affected processes after changing environment variables or mounted certificate files. For conda, consult its own SSL and proxy configuration rather than assuming pip settings apply.
Verification and reproducible results
After making one targeted change, rerun the original failing operation in the same environment and on the same network path. Then repeat the standard-library test or the relevant library-specific test. A repaired connection should complete certificate verification with hostname checking enabled; the application may still return an HTTP authorization error or an RPC error that needs separate investigation.
Record observations rather than guessing at success. The following table is a template: fill each result with your own output and omit secrets. Keep the before and after conditions comparable, including interpreter, endpoint hostname, proxy route, and CA bundle.
| Check | Before change | After change |
|---|---|---|
| Interpreter and client version | Record locally | Record locally |
| Network path and CA configuration | Record locally | Record locally |
| TLS verification result and error detail | Record locally | Record locally |
| HTTP or RPC result, if reached | Record locally | Record locally |
For an RPC integration, follow the TLS check with a non-destructive method supported by your network and client. Do not infer endpoint health solely from a GET response, and do not log API keys, authorization headers, or full URLs containing credentials.
Persistent failures, tradeoffs, and next steps
If the error persists, confirm that the running process actually reads the updated bundle and that the file is readable inside its execution environment. Check for a stale explicit verify or SSL context setting, a proxy that presents a different certificate, and an incomplete server chain. Compare evidence with the service operator or network administrator; provide the hostname, sanitized error, client versions, and relevant certificate issuer details, not secrets.
An explicit CA file makes trust auditable and portable but requires distribution and rotation. Using an operating-system store can simplify centrally managed trust, but only if the particular client and version actually use it. A private CA should be restricted to environments that need it. Disabling verification bypasses both chain and hostname checks, exposing credentials and responses to interception; it is not a sound workaround.
For an OnFinality integration, review the API service, check available networks, and use the RPC endpoint guide for endpoint concepts. Review RPC pricing and dedicated node options when planning infrastructure, and browse the Learn library for related implementation guidance. These resources do not replace diagnosis of the certificate actually presented on your connection.