Keycloak "Connection refused" service not ready in CI

A CI job called Keycloak before the server was accepting connections. Keycloak has a multi-second startup, so requests issued too early fail with connection refused rather than an auth error.

What this error means

A step gets "Connection refused" or a socket timeout against the Keycloak port while fetching a token or configuring a realm. It clears if the same request is retried once Keycloak is up.

curl: (7) Failed to connect to keycloak port 8080 after 0 ms: Connection refused

Common causes

Keycloak is still starting

The server takes time to boot the realm and HTTP listener; requests before that are refused at the socket level.

No readiness gate before the tests

The job starts tests immediately after launching Keycloak instead of waiting for it to be ready.

How to fix it

Wait for the Keycloak health endpoint

1. Poll the Keycloak readiness endpoint until it returns success.
2. Only then run the auth tests.
3. Add a service health check so dependents start after Keycloak is ready.

until curl -sf http://keycloak:8080/health/ready >/dev/null; do
  echo "waiting for keycloak..."; sleep 3
done

Give the service container a health check

Configure the Keycloak service with a health check so GitHub Actions waits for it before running steps.

services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    options: >-
      --health-cmd "curl -sf http://localhost:8080/health/ready"
      --health-interval 10s --health-retries 20

How to prevent it

• Gate auth tests behind a Keycloak readiness poll.
• Configure a health check on the Keycloak service container.
• Do not assume a container is ready the instant it starts.

Related guides