httpx Hints on self-signed certificates (Fix)

The Fix

Upgrade to version 0.13.0 or later.

Based on closed encode/httpx issue #507 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -362,3 +362,38 @@ is set to `None` or it cannot be inferred from it, HTTPX will default to
 }
 ```
+
+## SSL certificates
+

repro.py

# example.py
import httpx

# Use CA bundle generated by trustme
r = httpx.get("https://localhost:8000", verify="ca.pem")

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.13.0 or later.\nWhen NOT to use: This fix is not applicable for production environments requiring trusted certificates.\n\n

Why This Fix Works in Production

Trigger: Perhaps a "Custom SSL certificates" section in the Advanced docs, that shows how to use a `trustme` certificate in HTTPX…
Mechanism: Documentation lacked guidance on using self-signed certificates for local HTTP/2 requests
Why the fix works: Added documentation on using SSL certificates with HTTPX, addressing the need for self-signed certificates for local development. (first fixed release: 0.13.0).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Documentation lacked guidance on using self-signed certificates for local HTTP/2 requests
Production symptom (often without a traceback): Perhaps a "Custom SSL certificates" section in the Advanced docs, that shows how to use a `trustme` certificate in HTTPX…

Proof / Evidence

GitHub issue: #507
Fix PR: https://github.com/encode/httpx/pull/510
First fixed release: 0.13.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.77

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Related: https://github.com/encode/uvicorn/issues/47#issuecomment-550266244”

@lovelydinosaur · 2019-11-06 · source

“I just tried out trustme locally as well: Usage: 1. $ python create_certs.py 1. $ uvicorn --ssl-certfile=server.pem app:app 1. $ python example.py Have I got…”

@florimondmanca · 2019-11-06 · source

“Thanks @sethmlarson, it actually works great.”

@gvbgduh · 2019-11-06 · source

“(Btw I'm putting together a little utility that generates certificates in this configuration for you from command line)”

@sethmlarson · 2019-11-06 · source

Failure Signature (Search String)

Perhaps a "Custom SSL certificates" section in the Advanced docs, that shows how to use a `trustme` certificate in HTTPX…
1. `$ uvicorn --ssl-certfile=server.pem app:app`

Copy-friendly signature

signature.txt

Failure Signature
-----------------
Perhaps a "Custom SSL certificates" section in the Advanced docs, that shows how to use a `trustme` certificate in HTTPX…
1. `$ uvicorn --ssl-certfile=server.pem app:app`

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
Perhaps a "Custom SSL certificates" section in the Advanced docs, that shows how to use a `trustme` certificate in HTTPX…
1. `$ uvicorn --ssl-certfile=server.pem app:app`

Minimal Reproduction

repro.py

# example.py
import httpx

# Use CA bundle generated by trustme
r = httpx.get("https://localhost:8000", verify="ca.pem")

What Broke

Users faced difficulties making HTTPS requests to local servers due to missing SSL certificate instructions.

Why It Broke

Documentation lacked guidance on using self-signed certificates for local HTTP/2 requests

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 0.13.0 or later.

When NOT to use: This fix is not applicable for production environments requiring trusted certificates.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/encode/httpx/pull/510

First fixed release: 0.13.0

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix is not applicable for production environments requiring trusted certificates.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.
Add a TLS smoke test that performs a real handshake in CI (include CA bundle validation and hostname checks).
Alert on handshake failures by error string and endpoint to catch cert/CA changes quickly.

Version Compatibility Table

Version	Status
0.13.0	Fixed

Related Issues

No related fixes found.

Cluster: httpx:configuration-error All hubs All clusters

Related clusters: Data consistency Other Timeout

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.