NATS "no servers available for connection" in CI

By Daniel Zoghalchali·Latchkey

The NATS client tried every server in its list and none accepted a connection before the attempt budget ran out. In CI this is normally a readiness race: the test connects before nats-server is listening on 4222.

What this error means

The client fails with "nats: no servers available for connection" immediately on connect, then works once the server has finished starting.

nats: no servers available for connection

Common causes

The server is not listening yet

nats-server takes a moment to bind 4222. A connect during that window finds no reachable server.

Wrong server URL or port

The client URL points at a host or port the server does not serve, so the only listed server is unreachable.

How to fix it

Wait for the monitoring healthz before connecting

Enable the HTTP monitor and poll /healthz until the server reports ok.

services:
  nats:
    image: nats:2.10
    ports: ['4222:4222', '8222:8222']
    options: >-
      --health-cmd "wget -q -O- http://localhost:8222/healthz || exit 1"
      --health-interval 5s --health-retries 10

Point the client at the mapped address

Use the published host:port the server actually listens on.

env:
  NATS_URL: nats://localhost:4222

How to prevent it

• Gate the client on a NATS healthz check before connecting.
• Keep the client URL aligned with the mapped 4222.
• Allow the client a short reconnect window for the start race.

Frequently asked questions

Related guides

References

• GitHub Actions documentation