Pact "Could not connect to broker" (PACT_BROKER_BASE_URL) in CI

Unlike a 401 or 404, this failure happens before any HTTP response: the client could not open a connection to the broker URL. The base URL is wrong or unset, or the broker is unreachable from the runner network.

What this error means

Publish or verify fails with "Could not connect to the Pact Broker", "getaddrinfo ENOTFOUND", or "Connection refused" for the broker base URL.

Error making request to https://acme.pactflow.io
Failed to open TCP connection to acme.pactflow.io:443
getaddrinfo: Name or service not known

Common causes

PACT_BROKER_BASE_URL is unset or malformed

The variable is empty, missing the scheme, or has a typo, so the client cannot resolve or reach a valid host.

The broker is not reachable from the runner

A self-hosted broker behind a private network or firewall is not routable from the CI runner.

How to fix it

Set a correct, fully qualified base URL

1. Set PACT_BROKER_BASE_URL including the https:// scheme.
2. Confirm the host resolves and responds from the runner.
3. Re-run once connectivity is confirmed.

env:
  PACT_BROKER_BASE_URL: https://acme.pactflow.io
# quick reachability check from the runner:
# curl -sSf -o /dev/null "$PACT_BROKER_BASE_URL"

Make a private broker reachable

For a self-hosted broker, put the runner on the same network or expose the broker to the CI environment.

How to prevent it

• Always set an absolute broker base URL including the scheme.
• Add a one-line reachability check before publish or verify.
• Ensure self-hosted brokers are routable from your runners.

Related guides