Fastify Schema Validation & Serialization Diagnostics: A Practical Guide

Recognizable Condition

Clients receive a 400 with a message such as:

"body/querystring/params/headers validation failed"

and an array of validation errors, or a 200/500 response is sent but fields are missing or extra. The root cause is usually a mismatch between the incoming payload and the route’s schema, or a missing/incorrect response schema.

Cause & Diagnostic Table

Cause	Diagnostic Clue
Payload shape differs from schema	err.validation contains details; err.validationContext shows location
Schema attached to wrong location (body vs query)	err.validationContext indicates wrong property
Response schema missing status‑code key	Response contains fields not defined for the status code
Ajv options (coerceTypes/removeAdditional) mis‑configured	Unexpected coercion or stripping of fields
Custom error formatter hiding details	Only generic error message returned

Ordered Checks

1. Reproduce the failure
   • Save the failing request as a curl command.
   • Run it against a fresh instance with logging enabled.
2. Inspect the Fastify logger
   • Look for the validation field in the log line.
   • Note validationContext (e.g., body, querystring).
3. Compare payload to schema
   • Print the route’s schema from app.routes or the file.
   • Use a JSON diff tool or ajv directly to validate the raw payload.
4. Check Ajv configuration
   • Review app.setValidatorCompiler and ajvOptions used.
   • Confirm whether coerceTypes or removeAdditional are enabled.
5. Validate response schema
   • Ensure schema.response includes the status code returned.
   • Run the same request with --verbose to see the serialized output.
6. Isolate validation vs serialization
   • Temporarily comment out the route’s handler logic and return a static JSON.
   • Observe if the error persists.
7. Inspect custom error handlers
   • Check if app.setErrorHandler is masking validation details.

Fixes Tied to Findings

• Align schema or payload

  If the payload is missing a required field, add it or mark the field as nullable in the schema. If the payload has an extra field, either allow additionalProperties: true or remove the field from the request.

• Move fields to correct schema location

  For example, a header field defined in schema.body will never be validated. Move it to schema.headers.

  app.route({
    method: 'POST',
    url: '/example',
    schema: {
      body: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
      headers: { type: 'object', properties: { 'x-auth-token': { type: 'string' } }, required: ['x-auth-token'] }
    }
  });

• Enable coercion only when intended

  Set ajvOptions: { coerceTypes: true } in the validator compiler if you want string‑to‑number conversion. Otherwise keep it false to avoid silent data changes.

• Define schema.response per status code

  Fastify only serializes fields defined for the actual status code. If you return 200 but only defined 400 schema, the response will be empty.

  schema: {
    response: {
      200: { type: 'object', properties: { id: { type: 'integer' }, status: { type: 'string' } } },
      400: { type: 'object', properties: { error: { type: 'string' } } }
    }
  }

• Use a consistent error formatter

  Return validation details in a structured format that doesn’t expose the entire schema.

  app.setErrorHandler((error, request, reply) => {
    if (error.validation) {
      reply.status(400).send({ errors: error.validation });
    } else {
      reply.send(error);
    }
  });

• Re‑compile Ajv when schema changes

  Fastify caches compiled validators. After editing a schema file, restart the server or use app.close() and app.ready() to force recompilation.

Escalation Criteria

• After aligning schemas and payloads, the same 400 error still appears.
• Ajv throws a SchemaCompilationError during startup.
• Behavior changes between Fastify 4.x and 5.x releases.
• Potential prototype pollution detected (e.g., schema contains __proto__ keys).

When any of these occur, gather:

• Exact Fastify, Node.js, and Ajv version numbers.
• A minimal repro repository with package.json pinned to those versions.
• Redacted logs showing the full err.validation array.
• The route’s full schema definition.

Practical Verification Checklist

• Run npm test with a test that sends a valid payload and expects a 200.
• Run the same test with an invalid payload and assert a 400 and that err.validation.length > 0.
• Verify that app.hasRoute('/example') returns true after schema changes.
• Check that the response headers contain Content-Type: application/json and that no unexpected keys appear.

Conclusion

Fastify’s schema validation is powerful but can trip up developers when schemas, payloads, and Ajv options diverge. By following the ordered checks and applying fixes tied to the specific diagnostic clue, you can quickly restore correct request validation and response serialization. Keep your schemas DRY, document Ajv options, and use a consistent error formatter to avoid leaking sensitive information. When the problem persists beyond these steps, prepare a minimal reproducible example and consult the Fastify community or issue tracker.