python network_error ai_generated true

httpx.ConnectError: [Errno 111] Connection refused

ID: python/httpx-connect-error

Also available as: JSON · Markdown · 中文
80%Fix Rate
88%Confidence
0Evidence
2024-05-30First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3.8 active — — —
3.9 active — — —
3.10 active — — —
3.11 active — — —
3.12 active — — —

Root Cause

The target host/port is not accepting connections — the service is down, bound to a different interface, or a firewall is blocking.

generic

中文

目标主机/端口未接受连接——服务已停止、绑定到其他接口或防火墙拦截。

Workarounds

  1. 95% success 
    Verify the service is reachable:

curl -v http://host:port/
ss -tlnp | grep :port
  2. 90% success 
    In Docker Compose, use the service name (not localhost) as the host, and ensure depends_on with healthcheck.
  3. 85% success 
    Add a circuit breaker with tenacity and surface a clear error to callers.

Dead Ends

Common approaches that don't work:

  1. 85% fail

    If the service is down, retries fail identically.

  2. 90% fail

    TLS is not involved; the TCP connect fails before handshake.

  3. 95% fail

    Connection refused is immediate, not a timeout.