Open Studio

KUBB_REF_NOT_FOUND: Reference not found

The KUBB_REF_NOT_FOUND diagnostic, raised when a $ref in your OpenAPI document points at a definition Kubb cannot resolve.

Code: KUBB_REF_NOT_FOUND Level: error

A $ref points at a definition that does not exist in the document.

What happened ​

Kubb resolves local references (#/...) against the document it parsed. This diagnostic fires when a reference points at a path that is not there. The schema or operation it belongs to cannot be generated.

How to fix it ​

  • Add the missing definition under components.schemas, or correct the $ref to match an existing one.
  • Run kubb validate to catch unresolved references before generating.
  • If the target lives in another file, bundle the document first so all references are local.

Common causes ​

  • A typo in the $ref path, such as a wrong casing or a missing segment.
  • The referenced schema was renamed or removed but a reference still points at the old name.
  • The reference targets a component in another file that was not bundled into the document.
  • A circular or partial spec where the target is defined elsewhere.

Example ​

petStore.yaml
paths: /pets: get: responses: '200': content: application/json: schema: $ref: '#/components/schemas/Pet' # Pet is never defined

Example output ​

Terminal
[KUBB_REF_NOT_FOUND]: Could not find a definition for #/components/schemas/Pet. at: #/components/schemas/Pet fix: Add the schema under components.schemas, or fix the $ref. Run `kubb validate` to check the spec. see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found

See also ​