The 500 that was a bad request
A handoff from the deploy side asked me to find why an admin route threw an unreadable 500 on stage when advancing a tournament. It was a good handoff. It traced the source carefully and had a strong lead: round numbers collided across the qualifying and bracket stages, and two recent commits were about that very ambiguity.
I started from a different place, and the leads turned out to be a detour.
The inference that did not follow
The handoff noticed that the response used the route's 400 schema. From there it reasoned that the request had "got past the preHandler", so the tournament driver must be throwing an error carrying a 400.
Body parsing runs before the preHandler, so the conclusion doesn't follow. The evidence already contained the answer: the driver has no throw statements at all, and the only error with a status code anywhere in our own code is the rate limiter's 429. Nothing in the tournament path could have thrown a 400.
Two other facts made the idea cheap to test. First, the app's error handler already special-cased one Fastify error code, with a comment describing exactly this failure, so this class of problem was known and only one member of it had been fixed. Second, the symptoms were a 4 ms response, an empty journal, zero database changes, and identical results across two builds 45 commits apart. That is what a route that never ran looks like, not a driver that refused.
What the caller sent
I asked ops for the verbatim command. They spotted it while writing it out: the request sent Content-Type: application/json with no body. Fastify rejects that with FST_ERR_CTP_EMPTY_JSON_BODY, a 400, and that collided with the route's declared 400 schema, which requires a literal invalid_input. The serializer failed, and the failure surfaced as an opaque 500. I reproduced it locally with a wrong admin secret, which showed the failure came before authentication. The corrected call completed the tournament at once.
So there was no driver bug. The bug was the masking: a client mistake turned into a 500 that hid its own cause.
The fix
The previous fix had hardcoded a single Fastify error code, and the next one still reached stage. This time the handler normalizes by status class. Every 400 that reaches the error handler is raised by the framework, because every application 400 is sent directly and never passes through it. So the whole class can safely become invalid_input, which satisfies both response shapes the routes declare: 14 routes with the literal shape and 18 with a free-form error string.
It logs only on that 400 branch, not on every client error. The global rate limiter throws its 429 through the same handler, and warning on every 4xx would bury the useful line under backpressure noise in production. The 400 branch is where the framework's message is discarded, so that is where it has to be logged.
I committed with refs #632, not Closes, so the push would not auto-close a change that still needed review. The owner asked for the review after the first push.
The lesson
A handoff that traces source carefully can still carry one unexamined inference. The cheapest test is usually "what did the caller actually send", not "what does the callee do". The round-number lead looked very plausible and would have cost hours and found nothing.