A WireMock weight-log stub stopped answering after a teammate added a mapping. Why?

## Nothing changed about your stub The framing of this failure is what makes it hard. Your mapping was not edited, not removed and not invalidated; its criteria still fit the request exactly as they did yesterday. What changed is the *set* it competes in. WireMock gathers every mapping that matched an incoming request, sorts them, and serves the first. Adding a mapping that also matches changes the contents of that collection, and therefore can change which mapping comes first — without touching a single character of yours. That is why the useful first sentence in the diagnosis is a negative one: this is a precedence problem, not a matching problem. Your stub matched. It just was not first. ## The two ways a new mapping takes your requests 1. **It carries a lower `atPriority()` number.** Priority is WireMock's primary sort key and it sorts ascending, so any smaller number goes to the front regardless of when either mapping was registered. A colleague pinning their new stub at `atPriority(1)` will outrank yours at the default five permanently. 2. **It carries the same number and arrived later.** If neither stub calls `atPriority()`, both hold `DEFAULT_PRIORITY`, whose value is five. The priority key separates nothing, WireMock falls through to insertion index descending, and the most recently registered mapping wins. This is the common case, because most stub sets never write a priority number anywhere. Those are the only two possibilities, and distinguishing them tells you what to change. ## Reading the evidence - **Confirm the overlap first.** Line up the two mappings' criteria against one concrete request — say `GET /falconry/v1/birds/kestrel-7/weights` — and check that both really do fit it. If only one fits, precedence is not your problem. - **Compare the numbers.** If the new mapping's number is lower, case one; the ordering is explicit and permanent. - **Compare registration order only if the numbers tie.** Insertion order is never consulted for mappings that differ on priority, so a later mapping losing is proof the numbers already separated them. - **Look at what was actually served.** A response body or status that belongs to the other mapping is direct evidence that a different stub answered, as opposed to nothing answering. - **Do not reach for unmatched-request tooling.** The request matched something, so it is not an unmatched request; treating it as one sends you looking for a matcher bug that does not exist. ## Why "move my stubFor call later" is the wrong fix When both mappings sit at the default, moving your registration after theirs really does restore the old behaviour. It is still the wrong fix, for reasons that show up within weeks: - The ordering now lives in the execution order of fixtures, base classes and setup methods, which no reader of either mapping can see. - The next mapping anyone appends inherits the front of the queue, so the same failure recurs with a new author. - Refactoring that moves a `stubFor` call between a shared setup and a single test changes behaviour with no behavioural change in the diff. - A test that passes alone can fail in a suite, because the set contained different mappings at the moment the request arrived. ## The durable fix - **Pin the mapping that must win with an explicit low `atPriority()` number.** Once your stub holds a smaller number than the competitor, insertion order is never consulted and the ordering survives any reordering of the code. - **Or push the broad mapping down** with a high number if it is the one meant to answer only what nothing else claims. Either end works; what matters is that the ordering is written rather than inherited. - **Or remove the overlap entirely** by tightening one of the two mappings' criteria so they stop competing. This is the strongest outcome when it is available, because it needs no number at all. - **Record the intent next to the number**, naming the mapping it outranks, so the next person to add a competitor sees the claim instead of rediscovering it. ## What this costs when nobody notices The reason this is a senior question rather than a mechanical one is the failure's shape. Nothing errors. The suite may stay green, because the mapping that won can easily return a plausible response — and the test that depended on yours now asserts against someone else's stub. The signal is often a slow drift: a scenario that used to exercise a specific weight-log response is quietly exercising a general one, and the assertion still passes because it was never tight enough to tell them apart. So the judgment being tested is whether you go looking for the *other* mapping at all. A candidate who edits their own stub — loosening its matcher, adding fields, re-recording it — is debugging the wrong artefact. The stub that stopped answering is usually correct; the change that broke it is somewhere else in the set, and precedence is the mechanism that connects them.