Why does a WireMock stub set that works under java -jar return 404s in the wiremock/wiremock container?

## What WireMock's root directory actually is WireMock's standalone distribution is a shaded uber-jar — `wiremock-standalone` — that starts an HTTP server and builds its stub set from exactly one place: the **root directory**. Beneath that root it expects two subdirectories and looks nowhere else. - `mappings/` holds the JSON stub definitions the server will answer with. - `__files/` holds the body files those definitions reference by name. The root is chosen by `--root-dir`. When the flag is absent, WireMock roots itself in the process's current working directory. That single sentence explains the whole failure: nothing about your files changed between the laptop and the container, only what the process considers *here*. ## Why `java -jar` hides the problem On a developer machine you almost always launch the jar from the repository checkout that already contains `mappings/` and `__files/`. The default root and the checkout are the same directory, so the scaffolding-inspection stubs load and nobody ever thinks about `--root-dir`. The flag is invisible precisely because the default happened to be correct. The `wiremock/wiremock` image removes that coincidence. The container does not run inside your checkout — it roots the server at `/home/wiremock`, and that path holds none of your work until you put something there. An empty mapping set is not an error condition: WireMock starts happily, binds its port, and returns 404 to `GET /v1/scaffolds/SC-4471/inspections` because it genuinely has no stub for it. From outside, a healthy process with an empty stub set and a healthy process with a loaded one look identical. ## The three shapes of the same failure 1. **The mount landed one level too deep.** Mounting the checkout root produces `/home/wiremock/scaffolding-inspection-stubs/mappings`, while the server reads `/home/wiremock/mappings`. Every file is present inside the container and still invisible. 2. **The JSON sits directly under the mount target.** Copying `scaffold-inspections-list.json` straight into `/home/wiremock` puts it beside the directory WireMock reads rather than inside it. `mappings/` is not a convention you can drop. 3. **An argument moved the root.** Anything written after the image name is handed to the same launcher `java -jar` would have started, so a `--root-dir /tmp/stubs` left over from an experiment silently overrides the mount you just made. ## Diagnosing it in the order that costs least - **Prove the set is empty before you suspect matching.** List `/home/wiremock/mappings` inside the running container. An empty or missing directory ends the investigation there; a full one moves you to a genuinely different problem. - **Read the start-up output.** `--verbose` turns on WireMock's verbose logging to stdout, which is exactly where the container's logs already point. - **Check what the launcher was actually given.** Inspect the command the container is running: a forgotten `--root-dir` beats the mount every time. - **Confirm the request reached WireMock at all.** A host port that does not map to the server's port gives a connection failure, not a 404. If a 404 body came back from WireMock, the server received the request and had nothing to answer it with. - **Only then look at the mapping.** A stub that loaded and failed to match is a different class of problem with a different toolkit. ## Why 404 is the honest symptom The distinction worth demonstrating in an interview is between *nothing loaded* and *nothing matched*. Both surface as an unmatched request, so both look like a broken stub, and engineers reliably reach for the matcher first. The mechanical separator is the mapping set itself: if the server holds zero mappings, no matcher was ever consulted, and every minute spent loosening a URL pattern is wasted. That is why the first move is a directory listing rather than an edit. The same asymmetry explains why this failure survives code review. The mapping files are committed, reviewed and correct; the defect lives in the one line that says where the process should look, and that line usually sits in a pipeline definition nobody reads alongside the stubs. ## Keeping it from recurring - **Agree one layout.** Keep `mappings/` and `__files/` at the top of a dedicated stub directory in the repository, and always mount that directory — never one of its children. - **Mount the parent, publish the port, pass nothing else.** The fewer arguments after the image name, the fewer ways there are to move the root. - **Smoke-test the set, not the process.** Once the container is up, request one scaffolding-inspection path a mapping must answer and fail the job when it does not. Process liveness cannot tell you the set loaded; a request that a stub must answer can. - **Fail loudly on an empty set.** A build that quietly proceeds against a stub server holding no stubs produces test failures that read like application bugs, and the team spends a day inside the wrong repository. - **Keep the local and container launch in one script.** When the same file chooses both the root directory and the mount target, the two cannot drift apart.