What this error means

Every key under paths must map to a Path Item Object: a YAML mapping that holds operations like get and post. kin-openapi (github.com/getkin/kin-openapi) checks this while loading the document, in Loader.resolvePathItemRef inside openapi3/loader.go. If the value for a path key unmarshals to nil, the loader stops with this error before validation even starts.

That makes it a loading failure, not a lint warning. Calls like LoadFromFile or LoadFromData return the error and you get no document back.

Why kin-openapi emits it

A path key ends up with a null value in almost every real case. The two common ways to get there:

• A dedented operation. The get: block was indented one level too shallow, so YAML parses it as a sibling of the path instead of its child. The path key itself is left with nothing under it, which is null.
• A stub path. Someone sketched /health: as a placeholder and never filled it in. In YAML, a key with no value is null.

In the broken version, YAML gives paths two keys: /health (null) and get (an object). kin-openapi hits the null path item first and returns the error. If you delete a stub path instead of filling it in, the error also goes away; an empty mapping ({}) is technically a valid path item, but a bare key with no value is not.

Two wordings, one check

Depending on your kin-openapi version, the message reads either invalid path item: value MUST be a JSON object (early releases) or invalid path item: value MUST be an object (current releases). Same variable, same check: errMUSTPathItem in loader.go. If you are grepping the kin-openapi source for the older wording and finding nothing, that is why.

How to catch it earlier

Indentation slips are invisible in a diff and cheap to catch in the browser. Paste the spec into the free OpenAPI validator before it reaches your Go service; it flags null path items along with every other structural problem in one pass. The OpenAPI linter goes further and catches stub paths and other spec smells that load fine but bite later. In CI, npx @stoplight/spectral-cli lint openapi.yaml covers the same ground.

Frequently asked questions

Why does kin-openapi reject this when other validators accept it?

kin-openapi fails during loading, before validation, when a path value unmarshals to nil. Some JavaScript tools are lenient and treat an empty path item as an empty object. The OpenAPI spec requires every value under paths to be a Path Item Object, so the strict reading is the correct one.

My version says "value MUST be an object". Same error?

Yes. The wording changed between releases; the check did not. Both messages come from the nil path item check in openapi3/loader.go.

Can a $ref in paths cause this?

Yes. kin-openapi resolves path item $refs during loading. If the reference points at something that is not a path item mapping, the same error surfaces. Verify the target is a mapping with operations, not a schema or a null value.