OpenAPI — request validation failed against spec

An OpenAPI validator rejects a request because a parameter or body field does not match the schema defined in the specification for the path and method.

intermediatedebuggingopenapivalidation

Symptoms

error: Request validation failed for POST /path
A required parameter is missing or has the wrong type
The body does not match the requestBody schema

Possible causes

A required parameter or field is missing from the request
A field has the wrong type (string vs integer)
An enum value does not match the allowed values in the spec

Diagnosis steps

Compare the request against the spec

npx @redocly/openapi-cli lint openapi.yaml

Interpretation

Confirms the spec is valid; then compare the request fields against the schema.

Validate the specific request

npx openapi-request-validator --spec openapi.yaml --request request.json

Interpretation

Shows which field fails and why.

Root cause

The request does not conform to the OpenAPI schema for the path and method, so the validator rejects it before it reaches the handler.

Fix

Update the request to match the spec, or update the spec to accept the request shape. Ensure required fields are present and types match.

Verify the fix

Resubmit the corrected request and confirm validation passes; verify the handler processes it successfully.

Symptom walkthrough

An OpenAPI validator rejects a request because a parameter or body field does not match the schema defined in the specification for the path and method. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The request does not conform to the OpenAPI schema for the path and method, so the validator rejects it before it reaches the handler.

Fix

Update the request to match the spec, or update the spec to accept the request shape. Ensure required fields are present and types match. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Resubmit the corrected request and confirm validation passes; verify the handler processes it successfully. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

npx @redocly/openapi-cli lint openapi.yaml
npx openapi-request-validator --spec openapi.yaml --request request.json