Pact Broker Docker container not ready before publish in CI

When you run a pactfoundation/pact-broker container as a CI service, the broker needs its database up and its own boot to finish before it answers. A publish that fires too early hits a connection refused or 502 while the container is still starting.

What this error means

The publish or verify step fails with "Connection refused" or a 502/503 against the local broker URL immediately after the container starts, then works if retried later.

Pact Broker

Error making request to http://localhost:9292
Failed to open TCP connection to localhost:9292 (Connection refused)
# pact-broker container is still running database migrations

Common causes

Publish runs before the broker is healthy

The step starts as soon as the container is created, but the broker is still migrating the database and not yet serving.

No health check gate before the step

Nothing waits for the broker endpoint to return 200, so the first request races the container boot.

How to fix it

Wait for the broker health endpoint

Start the broker container and its database.
Poll the broker diagnostic endpoint until it returns 200.
Only then run publish or verify.

Terminal

# wait until the broker answers before publishing
until curl -sSf http://localhost:9292/diagnostic/status/heartbeat; do
  sleep 2
done

Use a service health check

Declare a health check on the broker service so dependent steps wait for it to be healthy.

.github/workflows/ci.yml

services:
  broker:
    image: pactfoundation/pact-broker
    options: >-
      --health-cmd "curl -f http://localhost:9292/diagnostic/status/heartbeat"
      --health-interval 5s --health-retries 10

How to prevent it

Gate publish and verify on a broker health check.
Wait for the broker heartbeat endpoint, not just container start.
Give the database and broker time to run migrations before use.