Flagsmith "Connection refused" to self-hosted instance in CI
The Flagsmith SDK could not open a TCP connection to the configured api_url. On a self-hosted deployment this usually means the API container is not listening yet, the URL is wrong, or the service is not on the CI network. Flagsmith then serves defaults or raises depending on your config.
What this error means
The SDK raises a connection error such as "Connection refused" or "Max retries exceeded" for the self-hosted api_url. Flags never load and behaviour falls back to defaults.
requests.exceptions.ConnectionError:
HTTPConnectionPool(host='flagsmith', port=8000): Max retries exceeded with url:
/api/v1/flags/ (Caused by NewConnectionError('Connection refused'))Common causes
The self-hosted API service is not ready yet
A Flagsmith container started as a CI service is still booting when the SDK connects, so the port is not accepting connections.
The api_url points at the wrong host or port
The URL uses localhost instead of the service hostname (or the wrong port), so no listener answers on the CI network.
How to fix it
Wait for the API to be healthy before running
Poll the health endpoint until the self-hosted instance responds, then start the steps that read flags.
until curl -sf http://flagsmith:8000/health; do sleep 2; doneUse the correct service hostname in the api_url
When Flagsmith runs as a service container, connect to its service name and mapped port, not localhost.
flagsmith = Flagsmith(
environment_key=os.environ["FLAGSMITH_ENVIRONMENT_KEY"],
api_url="http://flagsmith:8000/api/v1/",
)How to prevent it
- Gate flag-reading steps behind a health check on the self-hosted instance.
- Reference the service hostname, not localhost, from other containers.
- Give the Flagsmith container time and readiness checks before CI reads flags.