Does returning a plain object from Fastify's onSend hook bypass serialization entirely?

Answer

Yes. onSend runs after Fastify has already performed schema-based serialization. The payload you receive is a string, Buffer or stream. Returning a value from the hook replaces reply.payload and Fastify does not re-serialize it. A plain JavaScript object is therefore treated as the final payload, not serialized again.

With the default reply handling in Fastify v3 and v4, returning a non-string, non-Buffer, non-stream value causes a TypeError during the subsequent send step. It is not silently coerced to [object Object]. The same rule applies in Fastify v5 pre-releases, with possible wording changes to the error message. Behavior is version-dependent only in error text, not in the core type check.

Because serialization is skipped, Content-Length is not recomputed for the replacement value. If you return a string or Buffer you are responsible for correct headers; if you return an object the request fails before headers are finalized.

Confirmed facts

• onSend is after serialization. preSerialization is the hook for mutating the payload before schema serialization runs.
• Returning from onSend replaces the outgoing payload directly. No second serialization pass occurs.
• Default Fastify rejects plain objects on send with a TypeError rather than coercing them.

Likely explanation

The hook is intended for final modifications to an already-serialized body, e.g., compression, logging, or swapping to a string/Buffer. The implementation assumes the return type is a valid Node response body. Returning an object violates that assumption, so the send path errors.

Steps to verify for this case

1. Create a minimal Fastify app with an onSend hook that returns { foo: 'bar' }.
2. Send a request and observe server logs for a TypeError on send.
3. Repeat with return JSON.stringify({ foo: 'bar' }) to confirm a string payload is accepted.
4. Inspect response headers to confirm Content-Length is omitted or mismatched when the payload type is invalid.

Assumption: default Fastify reply handling, no custom reply.send override or custom serializer. Custom serializers or raw reply.raw.writeHead usage can change the outcome.

To give a precise recommendation, which Fastify major version and whether you use a custom serializer or reply override is needed.