Elasticsearch Python client "ConnectionError" in CI

The Elasticsearch Python client (elasticsearch-py) raised ConnectionError because it could not complete a request to the node: the cluster was not ready yet, the host or port was wrong, or the client used HTTP against an HTTPS (8.x) node. The transport wraps the underlying socket or TLS failure.

What this error means

The client raises "elastic_transport.ConnectionError: Connection error caused by: ..." naming a refused connection, a timeout, or a TLS problem against the configured host.

elastic_transport.ConnectionError: Connection error caused by:
ConnectionError(Connection refused)

Common causes

The client connected before the cluster was ready

The port opened but the cluster was not yet serviceable, so the first request failed with a connection error.

Wrong scheme, host, or port

An 8.x node serves HTTPS by default; a client configured for http:// or the wrong host cannot connect.

How to fix it

Wait for readiness, then connect with the right URL

1. Poll _cluster/health until yellow before constructing the client.
2. Use the correct scheme: http if security is disabled, https otherwise.
3. Point the client at the published host and port.

from elasticsearch import Elasticsearch
# security disabled in CI -> plain http
es = Elasticsearch("http://localhost:9200")
es.cluster.health(wait_for_status="yellow", timeout="30s")

Match the client to the node security settings

If security is on, use https and pass credentials and the CA; if it is off for CI, use plain http and no auth.

How to prevent it

• Wait for cluster health before the client sends real requests.
• Keep the client scheme in sync with the node security setting.
• Configure host and port from the workflow, not hard-coded assumptions.

Related guides