OpenAPI Validation Errors, Explained and Fixed

Each page in this reference covers one real validator error: the exact message, the tool that emits it, a minimal spec that reproduces it, and the corrected version. Paste the error, get the fix.

The Errors

invalid path item: value MUST be a JSON objectkin-openapi (Go)

A path key resolves to null instead of a path item, usually a dedented operation or an empty path entry.

See the fix

Property "produces" is not expected to be hereSpectral

A keyword sits at the wrong nesting level, or a Swagger 2.0 keyword is used in an OpenAPI 3.x document.

See the fix

Error resolving $ref pointer. Token "definitions" does not existswagger-cli / swagger-parser

A $ref pointer names a segment that does not exist in the document, often a Swagger 2.0 location or a typo.

See the fix

attribute paths.'/users'(get).responses is missingopenapi-generator

An operation has no responses object. OpenAPI requires at least one response per operation.

See the fix

Declared path parameter "id" needs to be defined as a path parameter at either the path or operation levelSwagger Editor

A {placeholder} in the path template has no matching parameter with in: path and required: true.

See the fix

$ref must not be placed next to any other propertiesSpectral

A description or other keyword sits beside a $ref in OpenAPI 3.0, where siblings of $ref are ignored.

See the fix

Not sure which error you have?

Paste your spec into the free OpenAPI validator to see every structural error at once, or run the OpenAPI linter for Spectral-style style and quality checks. For a broader tour of frequent failures, the guide to common OpenAPI validation errors covers the ten you will hit most often.

Validate and Publish Your API Docs

Specway validates your spec on import, highlights errors inline, and generates documentation from the valid portions while you fix issues.

Import Your Spec