Skip to main content

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 containsFix
does not existPaths are relative to the working directory – use { module: import.meta.url, file } (file sources)
is not a WireMock stub mappingA mapping needs request and response – is it a body for withFiles()?
invalid JSONFix the file or string
"mappings" must be a non-empty arrayAdd at least one stub
must be a relative path using "/" separatorsNo empty, absolute, . or .. name segments
is not installedInstall the package – looked up from the working directory
must point to a file inside packageRemove .. from file
is already registered from …Two sources for one path: rename one
stub id … is already used by …Two stubs share an id
examples/troubleshooting/errors.test.ts
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:

examples/container/container.test.ts
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)

examples/extensions/extensions.test.ts
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:

examples/troubleshooting/errors.e2e.test.ts
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 outputCause
ClassNotFoundExceptionThe class is in no JAR on the class path
UnsupportedClassVersionErrorThe JAR targets Java newer than 11
NoSuchMethodException, InstantiationExceptionThe 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:

EnvironmentFix
Remote or rootless daemonDOCKER_HOST=tcp://host:2375 or unix:///path/to/docker.sock
PodmanDOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock, TESTCONTAINERS_RYUK_DISABLED=true
Docker socket in a dev containerTESTCONTAINERS_HOST_OVERRIDE=host.docker.internal
No runtimeRun 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:

examples/troubleshooting/errors.e2e.test.ts
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:

examples/troubleshooting/errors.e2e.test.ts
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:

examples/stubs/stubs.e2e.test.ts
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.