fastify-troubleshooting

Fastify Troubleshooting & Anti-Patterns

You are diagnosing and fixing Fastify issues. Follow these rules strictly. Every section is organized by category with NEVER rules (things you must prevent) and BUG patterns (common mistakes to detect and fix).

Schema & Validation Issues

NEVER: Accept User-Provided Schemas

Never allow user-supplied JSON Schema objects to be passed into Fastify route schemas. Fastify's validation and serialization compilers (Ajv and fast-json-stringify) use new Function() internally to generate optimized code from schemas. If a user can control the schema definition, they can inject arbitrary JavaScript that executes on the server. Treat this as a CRITICAL security vulnerability with no exceptions. Always hardcode schemas in your route definitions or load them from trusted configuration files that users cannot modify.

NEVER: Use Ajv $async for Database Lookups

Never use Ajv's $async keyword to perform database reads during schema validation. Validation runs on every incoming request before your business logic, and async validators that hit the database open a denial-of-service vector where attackers can flood your validation layer with expensive queries. Move all async business logic validation (uniqueness checks, existence lookups, permission verification) into a preHandler hook where you have full control over execution flow, caching, and error handling.

BUG: anyOf with Nullable Primitives

When type coercion is enabled (which Fastify enables by default), using anyOf: [{ type: "number" }, { type: "null" }] causes unexpected coercion behavior. Values like 0 and false coerce to null instead of being treated as valid numbers or booleans. This happens because Ajv's coercion logic tries each branch of anyOf and null coercion takes precedence for falsy values. Fix this by using the nullable: true keyword on the type definition instead of anyOf. Write { type: "number", nullable: true } rather than the anyOf pattern for primitive nullable types.