Unleash "failed to fetch toggles" ECONNREFUSED in CI

The Unleash client tried to fetch its toggle configuration and the TCP connection to the API URL was refused. In CI this usually means the Unleash server (often a service container) is not listening yet, or the url is wrong. The client emits an error event and keeps the last known or bootstrap state.

What this error means

Unleash emits "Unleash Repository error" with an ECONNREFUSED cause, or "failed to fetch" for the /api/client/features endpoint. Toggles do not update and evaluations use bootstrap or default values.

Unleash

[unleash] Unleash Repository error: FetchError: request to
http://unleash:4242/api/client/features failed, reason: connect ECONNREFUSED 127.0.0.1:4242

Common causes

The Unleash server is not ready when the client connects

An Unleash service container is still starting, so nothing is listening on the API port when the client makes its first fetch.

The url points at the wrong host or port

Using localhost from another container, or the wrong port, means the connection has no listener to reach.

How to fix it

Wait for Unleash to be healthy

Poll the Unleash health endpoint until it answers before running steps that read toggles.

Terminal

until curl -sf http://unleash:4242/health; do sleep 2; done

Bootstrap toggles so the fetch is not required

Provide a bootstrap source so the client evaluates from a known state even if the first fetch fails.

unleash.js

const unleash = initialize({
  url: 'http://unleash:4242/api/',
  appName: 'ci',
  bootstrap: { data: require('./unleash-bootstrap.json') },
});

How to prevent it

Gate toggle reads behind an Unleash health check.
Use the correct service hostname and port from other containers.
Bootstrap the client so a slow server does not leave toggles unset.