Fastify bodyLimit: does a route-level override fully replace the global limit for all content types?

Answer to the core questions

1. Does a route‑level bodyLimit fully override the global value? Yes. In both Fastify v4 and v5 the value supplied on a route is used exclusively for that route. The framework does not compare the two values; it discards the global setting for that request path.

2. When is the limit enforced and does it apply to custom parsers? The check happens on the raw request body before any content‑type parser runs. All built‑in parsers (JSON, url‑encoded, text) honour the same threshold. If you register a custom parser that pulls the body from the stream outside Fastify’s interception layer, the limit may be bypassed unless the parser itself respects the bodyLimit value.

3. Is a route‑specific override the recommended pattern? Absolutely. Raising the global limit increases memory pressure for every concurrent request. Using a per‑route override confines the larger allowance to the upload endpoint, keeping other routes safe.

How it works in practice

1. Fastify starts a request and captures the incoming stream.
2. It calculates the effectiveLimit = route.bodyLimit if defined, otherwise server.bodyLimit.
3. While the stream is being accumulated, the size is compared to effectiveLimit. If exceeded, Fastify aborts the request and returns 413 Payload Too Large before any parser runs.
4. Once the stream is within limits, the appropriate parser is invoked.
5. Custom parsers that read the stream independently of Fastify’s interception can ignore the limit unless they explicitly check req.headers["content-length"] or req.rawBodyLength.

Recommended pattern for large‑payload routes

• Configure the route with bodyLimit: 20 * 1024 * 1024 (or whatever size you need).
• Keep the global bodyLimit at a conservative value, e.g., 1 * 1024 * 1024.
• If you use a custom parser, add a guard that checks req.rawBodyLength against the route’s bodyLimit and aborts with a 413 if necessary.
• Optionally, add a preHandler hook that logs the effective limit and the received body size for audit purposes.

What you need to verify in your setup

To be certain that your custom content‑type parser respects the limit, run a small test:

await fastify.inject({
  method: 'POST',
  url: '/upload',
  payload: Buffer.alloc(25 * 1024 * 1024), // 25 MB
  headers: { 'content-type': 'application/octet-stream' }
}).then(res => console.log(res.statusCode));

If you receive a 413, the parser is compliant. If not, you must add an explicit size check inside the parser.

Missing diagnostic detail

Do you register any custom content‑type parsers that read the body stream outside Fastify’s built‑in pipeline?