Prism mock server "connection refused" in CI

By Daniel Zoghalchali·Latchkey

Prism serves a mock API from your OpenAPI document. When tests hit the mock before prism mock is listening, or on the wrong host or port, the connection is refused and requests fail with ECONNREFUSED.

What this error means

Tests against the Prism mock fail with "connect ECONNREFUSED 127.0.0.1:4010" while Prism starts, or Prism never bound the expected port.

Error: connect ECONNREFUSED 127.0.0.1:4010
  (test could not reach the Prism mock server)

Common causes

Prism was not started or is still booting

Prism runs as a background process; tests fired before it began listening on its port, so the connection is refused.

Prism bound a different host or port

Prism defaults to port 4010 and 127.0.0.1; tests targeting another host or port cannot connect.

How to fix it

Start Prism and wait before testing

1. Start prism mock in the background, binding an explicit host and port.
2. Poll the mock until it responds.
3. Run the tests against the confirmed-ready URL.

- run: npx @stoplight/prism-cli mock -h 0.0.0.0 -p 4010 openapi.yaml &
- run: |
    for i in $(seq 1 30); do curl -sf http://localhost:4010/health && break; sleep 1; done
- run: npm test

Point tests at the exact mock URL

Set the base URL your tests use to the host and port Prism actually binds.

export API_BASE_URL=http://localhost:4010

How to prevent it

• Wait for the Prism mock to be ready before tests run.
• Bind Prism to an explicit host and port your tests target.
• Fail clearly if the mock never comes up.

Frequently asked questions

Related guides

References

• GitHub Actions documentation