[bug] Proxy TLS handshake failures leak ACTIVE connections and cause PoolTimeout in sequential sync requests

[wirsnow]

With httpx2==2.12.0 and httpcore2==2.12.0, a TLS handshake failure after a successful HTTP proxy CONNECT leaves the tunnel connection in the pool with an ACTIVE state.

Each failure consumes another connection-pool slot. Once the number of failed handshakes reaches max_connections, subsequent requests raise PoolTimeout, even though all requests are synchronous and executed sequentially in a single thread.

This appears to be the same defect reported in the original HTTPX transport dependency, encode/httpcore discussion #921. A proposed upstream fix is available in encode/httpcore PR #1087.

Environment

• Python: CPython 3.12.12
• System: Windows
• httpx2==2.12.0
• httpcore2==2.12.0

The reproduction below was executed in an isolated environment without application imports or compatibility patches.

Minimal reproduction

Save the following as httpx2_pooltimeout.py and run:

uv run --no-project --script httpx2_pooltimeout.py

# /// script
# requires-python = ">=3.10"
# dependencies = ["httpx2==2.12.0"]
# ///
"""
Run: uv run --no-project --script httpx2_pooltimeout.py
Expected: all three requests raise ConnectError and leave no pooled connections.
Actual: two failed TLS handshakes leave ACTIVE connections; request 3 raises PoolTimeout.
"""

import platform

import httpcore2
import httpx2


class FailingTLSStream:
    def read(self, max_bytes, timeout=None):
        return b"HTTP/1.1 200 Connection established\r\n\r\n"

    def write(self, data, timeout=None):
        pass

    def close(self):
        pass

    def get_extra_info(self, name):
        return None

    def start_tls(self, ssl_context, server_hostname=None, timeout=None):
        self.close()  # Match the real backend's socket cleanup on TLS failure.
        raise httpcore2.ConnectError("simulated TLS handshake failure")


class FakeProxyBackend:
    def connect_tcp(self, *args, **kwargs):
        return FailingTLSStream()


def main():
    print(f"Python {platform.python_version()}, httpx2 {httpx2.__version__}, httpcore2 {httpcore2.__version__}", flush=True)
    transport = httpx2.HTTPTransport(proxy="http://proxy.invalid:8080", verify=False, limits=httpx2.Limits(max_connections=2))
    transport._pool._network_backend = FakeProxyBackend()

    with httpx2.Client(transport=transport, trust_env=False, timeout=httpx2.Timeout(1, pool=0.01)) as client:
        for attempt in range(1, 4):
            print(f"Request {attempt}", flush=True)
            try:
                client.get("https://example.invalid/")
            except httpx2.ConnectError:
                print(f"ConnectError; pooled connections: {transport._pool.connections!r}", flush=True)
            # PoolTimeout is intentionally not caught, so the bug produces a traceback.


if __name__ == "__main__":
    main()

Expected behavior

All three requests should raise the simulated ConnectError. After each TLS failure, the failed tunnel connection should be closed and removed from the pool, leaving a slot available for the next request.

If TLS succeeds on a later attempt, that request should be able to complete using the same client.

Actual behavior

Request	Result	Connections retained in the pool
1	ConnectError	1, marked ACTIVE
2	ConnectError	2, both marked ACTIVE
3	PoolTimeout	No slot becomes available

The retained entries are reported as TunnelHTTPConnection objects with HTTP/1.1, ACTIVE, Request Count: 1.

Python 3.12.12, httpx2 2.12.0, httpcore2 2.12.0
Request 1
ConnectError; pooled connections: [<TunnelHTTPConnection ['http://proxy.invalid:8080', HTTP/1.1, ACTIVE, Request Count: 1]>]
Request 2
ConnectError; pooled connections: [<TunnelHTTPConnection ['http://proxy.invalid:8080', HTTP/1.1, ACTIVE, Request Count: 1]>, <TunnelHTTPConnection ['http://proxy.invalid:8080', HTTP/1.1, ACTIVE, Request Count: 1]>]
Request 3
Traceback (most recent call last):
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_transports\default.py", line 98, in map_httpcore_exceptions
    yield
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_transports\default.py", line 245, in handle_request
    resp = self._pool.handle_request(req)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpcore2\_sync\connection_pool.py", line 242, in handle_request
    raise exc from None
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpcore2\_sync\connection_pool.py", line 220, in handle_request
    connection = pool_request.wait_for_connection(timeout=timeout)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpcore2\_sync\connection_pool.py", line 35, in wait_for_connection
    self._connection_acquired.wait(timeout=timeout)
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpcore2\_synchronization.py", line 286, in wait
    raise PoolTimeout()  # pragma: no cover
    ^^^^^^^^^^^^^^^^^^^
httpcore2.PoolTimeout

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "E:\xxx\repro_httpx2_pooltimeout.py", line 56, in <module>
    main()
  File "E:\xxx\repro_httpx2_pooltimeout.py", line 49, in main
    client.get("https://example.invalid/")
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_client.py", line 1113, in get
    return self.request(
           ^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_client.py", line 797, in request
    return self.send(request, auth=auth, follow_redirects=follow_redirects)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_client.py", line 980, in send
    response = self._send_handling_auth(
               ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_client.py", line 1008, in _send_handling_auth
    response = self._send_handling_redirects(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_client.py", line 1043, in _send_handling_redirects
    response = self._send_single_request(request)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_client.py", line 1076, in _send_single_request
    response = transport.handle_request(request)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_transports\default.py", line 244, in handle_request
    with map_httpcore_exceptions():
         ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxx\AppData\Roaming\uv\python\cpython-3.12.12-windows-x86_64-none\Lib\contextlib.py", line 158, in __exit__
    self.gen.throw(value)
  File "C:\Users\xxx\AppData\Local\uv\cache\environments-v2\repro-httpx2-pooltimeout-3f2435e9e85a8126\Lib\site-packages\httpx2\_transports\default.py", line 115, in map_httpcore_exceptions
    raise mapped_exc(message) from exc
httpx2.PoolTimeout

Suspected cause

In [TunnelHTTPConnection.handle_request()] https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_sync/http_proxy.py), the proxy CONNECT request succeeds
before stream.start_tls(...) is called. If TLS setup raises, the enclosing connection object is not explicitly closed on that path.

Closing the underlying network stream does not itself update the HTTP connection object's state. The tunnel can therefore remain ACTIVE, making it neither reusable nor eligible for normal idle-connection cleanup.

The connection pool's exception handler removes the failed request from
its queue, but that does not remove the stale active connection entry. Repeating this sequence exhausts the configured connection limit.

Related upstream report and proposed fix

• encode/httpcore discussion #921 describes the same CONNECT/TLS failure sequence and eventual pool exhaustion in the asynchronous implementation. The reproducer in this report demonstrates the synchronous variant.
• encode/httpcore PR #1087 proposes closing the tunnel connection when TLS setup raises. Its diff includes both synchronous and asynchronous implementations and regression tests.

[itzzdev09]

Root-caused and fixed this, verified against a live repro — not just theorizing.

Confirming the repro

Ran the OP's script unmodified against httpx2==2.12.0 / httpcore2==2.12.0, Python 3.12.10, Windows:

Request 1
ConnectError; pooled connections: [<TunnelHTTPConnection [..., ACTIVE, Request Count: 1]>]
Request 2
ConnectError; pooled connections: [<TunnelHTTPConnection [...], <TunnelHTTPConnection [...]]
Request 3
PoolTimeout; pooled connections: [... same 2 stale entries ...]

Matches the report exactly.

The exact line

httpcore2/_sync/http_proxy.py, TunnelHTTPConnection.handle_request():

288  stream = connect_response.extensions["network_stream"]
...
300  with Trace("start_tls", logger, request, kwargs) as trace:
301      stream = stream.start_tls(**kwargs)

Compare this to the block twelve lines above it, which handles the other way CONNECT can fail (non-2xx status):

281  if connect_response.status < 200 or connect_response.status > 299:
282      ...
285      self._connection.close()
286      raise ProxyError(msg)

That path explicitly closes self._connection (the raw HTTPConnection used for the CONNECT handshake) before propagating the error. The start_tls() call three lines later has no equivalent — if it raises, the function exits via the exception with self._connection still pointing at that same CONNECT-phase HTTPConnection, which already completed one successful request (the CONNECT) and is therefore correctly, accurately reporting itself as ACTIVE/Request Count: 1 to the pool. It isn't lying or corrupted — nothing ever told it the tunnel died. self._connected (line 263) correctly stays False, but that flag only gates this TunnelHTTPConnection's own re-entry; it does nothing for the pool, which iterates self._connections directly.

And in connection_pool.py, handle_request()'s exception handler:

234  except BaseException as exc:
235      ...
238      self._requests.remove(pool_request)

only removes the pending request from the queue — it never touches self._connections. So the pool has no independent mechanism to notice the connection object is now a stale zombie; it fully trusts that object's own is_closed()/is_available(), and that object is (accurately, given what it knows) reporting itself as busy-but-fine.

The fix

Wrap start_tls() the same way the status-check block above it already does, and close the pre-TLS connection on any failure:

with Trace("start_tls", logger, request, kwargs) as trace:
    try:
        stream = stream.start_tls(**kwargs)
    except BaseException:
        self._connection.close()
        raise

Same change needed in httpcore2/_async/http_proxy.py — identical code shape there (stream = await stream.start_tls(**kwargs) at the same line number, same missing try/except), so this isn't sync-only.

Proof it works

Patched the installed package locally and re-ran the exact same unmodified repro script:

Request 1
ConnectError; pooled connections: []
Request 2
ConnectError; pooled connections: []
Request 3
ConnectError; pooled connections: []

All three now fail cleanly with ConnectError, zero leaked connections, exactly the "Expected behavior" the OP specified — and this confirms max_connections is never artificially exhausted regardless of how many consecutive TLS failures occur.

One nuance from tracing this: self._connection.close() here closes the CONNECT-phase HTTPConnection, not the raw TLS-wrapped stream object — that's correct, because at the failure point self._connection is still that pre-upgrade object (the reassignment to HTTP11Connection/HTTP2Connection only happens after start_tls succeeds, lines 309-322). The FailingTLSStream.close() in the repro's own mock already handles the socket-level cleanup separately; the pool-visible state (ACTIVE vs removable) is what self._connection.close() fixes.

This is a minimal, mechanical two-line-per-file fix — happy to open the PR against pydantic/httpx2 with this plus a regression test mirroring the OP's script if that's useful, since the upstream encode/httpcore#1087 fix apparently hasn't propagated to this fork yet.

[wirsnow]

May I submit an issue report?