Python "urllib3 NewConnectionError" in CI

By Kaveh Alemi·Latchkey

urllib3.exceptions.NewConnectionError: Failed to establish a new connection: [Errno 111] Connection refused is the low-level cause behind many requests ConnectionErrors: the TCP connect itself failed.

What this error means

A traceback shows "NewConnectionError('...: Failed to establish a new connection: [Errno 111] Connection refused')" beneath a requests or urllib3 call.

urllib3.exceptions.NewConnectionError: <...>: Failed to establish a new connection: [Errno 111] Connection refused

Common causes

Nothing is listening on the target host:port

A dependent service has not started, crashed, or is bound to a different port.

Wrong host inside the CI network

The code used localhost where the service runs under a different container hostname.

How to fix it

Point at the right address and wait for the listener

1. Verify the host and port match where the service actually listens in CI.
2. Use the service container hostname (not localhost) in container-network CI.
3. Poll the port until it accepts connections before running dependent tests.

# in containerized CI, use the service name, not localhost
DB_HOST = "postgres"  # docker/compose service name

How to prevent it

• On Latchkey managed runners, transient connection-refused failures during service warm-up are auto-retried.
• Use service hostnames in containerized CI networks.
• Gate connections on a port-readiness poll.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation