Skip to content

Improve SSL error message with helpful hints (#3713) - #3748

Open
rodrigobnogueira wants to merge 1 commit into
encode:masterfrom
rodrigobnogueira:fix/ssl-error-message-3713
Open

Improve SSL error message with helpful hints (#3713)#3748
rodrigobnogueira wants to merge 1 commit into
encode:masterfrom
rodrigobnogueira:fix/ssl-error-message-3713

Conversation

@rodrigobnogueira

@rodrigobnogueira rodrigobnogueira commented Jan 15, 2026

Copy link
Copy Markdown

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.

@rodrigobnogueira
rodrigobnogueira force-pushed the fix/ssl-error-message-3713 branch from 9c25d4f to 978b5f1 比较 July 9, 2026 05:46
注册 for free to join this conversation on GitHub. Already have an account? 登录 to comment

标签

None yet

Development

Successfully merging this pull request may close these issues.

1 participant