NATS "nats: timeout" on connect or request in CI

A NATS operation did not finish within its deadline. On connect it usually means the server was not ready in time; on a request it usually means no subscriber answered the subject before the timeout.

What this error means

The client fails with "nats: timeout" during connect, a request-reply call, or a flush, with no other error detail.

Terminal

nats: timeout

Common causes

The server was not ready within the connect deadline

A short connect timeout expires while nats-server is still binding 4222.

A request had no responder on the subject

A request-reply call times out because no consumer was subscribed to answer that subject yet.

How to fix it

Wait for readiness, then connect

Gate the client on the healthz endpoint so connect does not race startup.

Terminal

until wget -q -O- http://localhost:8222/healthz | grep -q ok; do
  echo "waiting for nats"; sleep 2
done

Start the responder before the request

Ensure the subscriber for the request subject is connected before the requester sends, or raise the request timeout.

Subscribe the responder and confirm it is ready.
Send the request only after the subscription is active.
Increase the request timeout for slow CI hardware if needed.

How to prevent it

Wait for the server healthz before connecting.
Order responders before requesters in request-reply tests.
Use timeouts sized for CI, not a developer laptop.