fastify-hooks-lifecycle

Fastify Hook Lifecycle Reference

You are working with Fastify's hook system. Follow every rule in this document precisely. Violations of the critical rules below cause silent double executions, lost context, and runtime exceptions that are difficult to trace.

General Hook Rules (CRITICAL)

Obey these rules in every hook you write. There are no exceptions.

• NEVER mix async/await with the done callback. If the hook function is declared async, do not accept or call done. If the hook uses done, do not use async or return a Promise. Mixing the two causes double execution of downstream hooks and handlers.
• NEVER use arrow functions as hook handlers. Arrow functions do not bind this, which means you lose access to the Fastify instance context (this is the encapsulating Fastify server). Always use function declarations or expressions.
• When you need to short-circuit the request lifecycle from an async hook, call reply.send() and then return reply. If you forget return reply, Fastify continues executing the remaining lifecycle, resulting in double execution and potential "Reply already sent" errors.
• Hooks can be either global or encapsulated. A hook registered inside a plugin that uses fastify-plugin (which breaks encapsulation) becomes global. A hook registered inside a normal plugin is scoped to that plugin and its children only. Be intentional about which you need.
• Every hook that accepts a done callback MUST call it. Failing to call done hangs the request indefinitely.
• Do not perform heavy synchronous work inside hooks. Fastify is single-threaded; blocking the event loop in a hook blocks all concurrent requests.

Request/Reply Hooks (Execution Order)

These hooks execute in the order listed below for every incoming request. Understand exactly where in the lifecycle each hook fires and what data is available at that point.

1. onRequest

This is the first hook that fires, before any parsing occurs.

• Signature: function (request, reply, done) (or async function (request, reply))
• request.body is UNDEFINED at this point. The request body has not been parsed yet. Do not attempt to read it.
• request.params, request.query, and request.headers ARE available.
• Use this hook for: early authentication checks (e.g., verifying a JWT before doing any work), request logging, IP-based rate limiting, early redirects, and attaching request-scoped metadata.
• To deny a request, call reply.code(401).send({ error: 'Unauthorized' }) and return reply (in async hooks) or call done(error) (in callback hooks).