Pact "state change request failed" in CI

By Kaveh Alemi·Latchkey

When you use an HTTP state change endpoint, the verifier POSTs each provider state to that URL before replaying the interaction. A "state change request failed" means that POST errored or the endpoint was unreachable.

What this error means

Verification aborts an interaction with "state change request failed" or a non-2xx from the state change URL, before the request under test is sent.

Given order 42 exists
  State change request to http://localhost:8080/_pact/provider_states failed:
  Connection refused (Connection refused)

Common causes

The state change endpoint is wrong or not mounted

The stateChangeUrl points at a path the provider does not serve, or the provider does not expose a provider-states endpoint at all.

The provider is not up when the state POST fires

The state change request runs before the provider finished booting, so the connection is refused.

How to fix it

Expose and target the correct state endpoint

1. Mount a provider states endpoint that applies the requested state.
2. Set stateChangeUrl (or use in-process stateHandlers) to that route.
3. Ensure the provider is health-checked before verification begins.

// Ruby/JS providers commonly mount:
//   POST /_pact/provider_states  { consumer, state }
stateChangeUrl: 'http://localhost:8080/_pact/provider_states'

Prefer in-process state handlers

Where the framework supports it, use stateHandlers so no separate HTTP endpoint has to be reachable.

How to prevent it

• Health-check the provider before state change requests fire.
• Keep the state change URL and the provider route in sync.
• Prefer in-process state handlers to avoid a separate endpoint.

Frequently asked questions

Related guides

References

• GitHub Actions documentation