Skip to content

Conversation

@rodrigobnogueira
Copy link

@rodrigobnogueira rodrigobnogueira commented Jan 15, 2026

Improve SSL error message with helpful hints

Relates to #3713

Summary

When encountering [SSL: WRONG_VERSION_NUMBER] or [SSL: RECORD_LAYER_FAILURE] errors, the error message now includes a helpful hint about possible causes.

Changes

httpx/_transports/default.py:
Enhanced map_httpcore_exceptions to detect SSL handshake failures and append guidance.

Before:

ConnectError: [SSL: WRONG_VERSION_NUMBER] wrong version number (_ssl.c:1000)

After:

ConnectError: [SSL: WRONG_VERSION_NUMBER] wrong version number (_ssl.c:1000) (Hint: HTTPS to HTTP server, or stale connection pool)

The commited hint is a small message, but we could add a more detailed message, such as:

               " (Possible causes: 1) Connecting via HTTPS to an HTTP server, "
               "2) A pooled connection was closed by the server - "
               "try setting `limits=httpx.Limits(keepalive_expiry=2)` or retrying)"

Context

Users experiencing intermittent SSL errors in long-running containers (like the ECS scenario in #3713) face cryptic OpenSSL messages. The root cause is typically stale connections being reused after the server silently closed them. This hint points users in the right direction.

Tests

Added test_ssl_error_message_enhancement in tests/test_exceptions.py.

Checklist

  • I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
  • I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
  • I've updated the documentation accordingly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant