WireMock "connection refused" / no stub matched in CI

WireMock serves stubbed HTTP responses. Two CI failures are common: tests hit it before the server or container is ready (connection refused), or a request matches no stub so WireMock returns 404 with a "Request was not matched" message.

What this error means

Tests fail with "Connection refused" to the WireMock port while it starts, or requests come back 404 with WireMock's "Request was not matched" body.

Request was not matched
No response could be served as there are no stub mappings in this WireMock instance.

Common causes

WireMock was not ready when tests ran

The WireMock server or container had not finished starting, so the connection was refused for early requests.

No stub mapping matched the request

The request method, path, or headers do not match any loaded stub, so WireMock returns 404 "Request was not matched".

How to fix it

Wait for WireMock and load mappings

1. Start WireMock and poll its admin endpoint until it responds.
2. Load the stub mappings the tests expect (mounted files or the admin API).
3. Run the tests once WireMock is ready and stubbed.

- run: |
    for i in $(seq 1 30); do curl -sf http://localhost:8080/__admin/mappings && break; sleep 1; done
- run: npm test

Make the stub match the request

Register a mapping whose method, URL, and matchers align with what the test sends so WireMock stops returning 404.

{
  "request": { "method": "GET", "url": "/users/1" },
  "response": { "status": 200, "jsonBody": { "id": 1, "name": "Ada" } }
}

How to prevent it

• Wait for WireMock's admin endpoint before running tests.
• Load stub mappings that match the requests under test.
• Assert on WireMock's "Request was not matched" body to catch stub gaps early.

Related guides