Troubleshooting
Find your error message below. Messages start with the method that failed, e.g.
WiremockContainer.withMapping("health"): ….
Registration errors
Thrown by withMappings(), withMapping() and withFiles():
| Error contains | Fix |
|---|---|
does not exist | Paths are relative to the working directory – use { module: import.meta.url, file } (file sources) |
is not a WireMock stub mapping | A mapping needs request and response – is it a body for withFiles()? |
invalid JSON | Fix the file or string |
"mappings" must be a non-empty array | Add at least one stub |
must be a relative path using "/" separators | No empty, absolute, . or .. name segments |
is not installed | Install the package – looked up from the working directory |
must point to a file inside package | Remove .. from file |
is already registered from … | Two sources for one path: rename one |
stub id … is already used by … | Two stubs share an id |
it.each<[string, () => unknown, string]>([
["a directory without mappings/", () => container().withMappings("./stubs/fixtures"), 'mappings" does not exist'],
["a missing file", () => container().withMapping("health", "./stubs/health.json"), 'health.json" does not exist'],
["a JSON file that is not a stub", () => container().withMapping("x", "./__mocks__/wiremock/__files/body-payments.json"), "is not a WireMock stub mapping"],
["malformed JSON", () => container().withMapping("x", { json: "{ request: {} }" }), "invalid JSON"],
["an empty { mappings }", () => container().withMapping("x", { json: { mappings: [] } }), '"mappings" must be a non-empty array'],
["a name leaving mappings/", () => container().withMapping("../ping", { json: ping }), 'must be a relative path using "/" separators'],
["a package that is not installed", () => container().withMapping("x", { package: "@acme/stubs", file: "x.json" }), 'package "@acme/stubs" is not installed'],
[
"a path leaving its package",
() => container().withMapping("x", { package: "@examples/payments-stubs", file: "../../package.json" }),
'must point to a file inside package "@examples/payments-stubs"',
],
["a file registered twice", () => container().withMapping("ping", { json: ping }).withMapping("ping", { json: ping }), "is already registered from inline JSON"],
])("%s", (_, register, message) => {
expect(register).toThrow(message);
});
Source: examples/troubleshooting/errors.test.ts (lines 15–31)
Extension errors
See authoring extensions → troubleshooting.
Errors when starting
start() rejects before starting anything on conflicting options or an unknown extension class:
it("an option set twice with different values fails start() – WireMock would crash", async () => {
const journal = { getName: () => "journal", getOptions: () => ["--max-request-journal=5"] };
const container = new WiremockContainer().withCommand(["--max-request-journal=1000"]).withExtension(journal);
await expect(container.start()).rejects.toThrow(
'option "--max-request-journal=5" conflicts with "--max-request-journal=1000" set by withCommand() or WIREMOCK_OPTIONS',
);
});
it("--extensions belongs to withExtension(), not withCommand()", async () => {
const container = new WiremockContainer()
.withCommand(["--extensions", "com.example.Other"])
.withExtension("com.github.tomakehurst.wiremock.extension.responsetemplating.ResponseTemplateTransformer");
await expect(container.start()).rejects.toThrow('"--extensions" is already set by withCommand() or WIREMOCK_OPTIONS');
});
Source: examples/container/container.test.ts (lines 23–36)
it("a class in none of the registered JARs fails start() with a suggestion", async () => {
const typo = new WiremockContainer().withExtensionJar(JARS.examples).withExtension("com.acme.UppercaseTransformer");
await expect(typo.start()).rejects.toThrow(`did you mean "${JAVA_PACKAGE}.UppercaseTransformer"?`);
});
Source: examples/extensions/extensions.test.ts (lines 200–203)
If WireMock itself fails, the error lists the extensions in use:
it("WireMock failing to start: the error names the extensions in use", async () => {
const start = new WiremockContainer()
.withExtensionJar(JARS.examples)
.withExtension("com.hellaweb3.wiremock.extensions.Missing") // in no JAR: WireMock cannot load it
.withExtensionOptions({ verifyClassNames: false }) // skips the check that would catch it before start-up
.withStartupTimeout(20_000) // Docker: the crashed container never binds its port
.start();
await expect(start).rejects.toThrow(
"WireMock was started with extensions: com.hellaweb3.wiremock.extensions.Missing; JARs: example-extensions.jar.",
);
});
Source: examples/troubleshooting/errors.e2e.test.ts (lines 38–49)
| In WireMock's output | Cause |
|---|---|
ClassNotFoundException | The class is in no JAR on the class path |
UnsupportedClassVersionError | The JAR targets Java newer than 11 |
NoSuchMethodException, InstantiationException | The class lacks a public no-argument constructor |
See WireMock's output with DEBUG=testcontainers:containers, or await wiremock.logs().
No container runtime
Could not find a working container runtime strategy – Testcontainers found no Docker:
| Environment | Fix |
|---|---|
| Remote or rootless daemon | DOCKER_HOST=tcp://host:2375 or unix:///path/to/docker.sock |
| Podman | DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock, TESTCONTAINERS_RYUK_DISABLED=true |
| Docker socket in a dev container | TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal |
| No runtime | Run without Docker, or Testcontainers Cloud |
Timeout on the first run
The first start() pulls the image. Raise the beforeAll timeout (the examples use 120_000), or
docker pull wiremock/wiremock beforehand.
Errors at runtime
countRequests(), findRequests(), reset() and resetRequests() throw WireMock's explanation
when it rejects a call – usually a malformed matcher:
it("a malformed matcher: WireMock's own explanation is in the error", async () => {
await using wiremock = await paymentsApi().start();
await wiremock.waitUntilReady();
const count = wiremock.countRequests({ urlPath: "/payments", queryParameters: { page: { equalTo: 2 } } }); // not "2"
await expect(count).rejects.toThrow(
"WireMock admin request POST /__admin/requests/count failed with 422 Unprocessable Entity",
);
await expect(count).rejects.toThrow("equalTo operand must be a non-null string");
});
Source: examples/troubleshooting/errors.e2e.test.ts (lines 13–23)
waitUntilReady() throws when WireMock is not healthy in time:
it("waitUntilReady() gives up after its timeout", async () => {
const wiremock = await paymentsApi().start();
await wiremock.stop();
await expect(wiremock.waitUntilReady({ timeout: 1_000, interval: 100 })).rejects.toThrow(
`WireMock at ${wiremock.rpcUrl} was not ready within 1000ms`,
);
});
Source: examples/troubleshooting/errors.e2e.test.ts (lines 27–34)
A request is not matched
WireMock answers 404 with a Request was not matched report of the closest stubs – print the
response body. List what WireMock loaded:
it("the admin API lists every registered stub", async () => {
const { mappings } = (await (await fetch(wiremock.getMappingUrl())).json()) as { mappings: unknown[] };
expect(mappings).toHaveLength(11); // 2 recorded + 1 + 1 + 2 + 1 + 1 + 1 + 2
});
Source: examples/stubs/stubs.e2e.test.ts (lines 69–72)
Usual causes: url (exact path and query) where urlPath was meant, a method mismatch, or a
header your client does not send.