Skip to content

"invalid-ref ... does not exist" and "Can't resolve $ref": finding a broken reference

Last checked and updated

A $ref is an address: a file (optional) and a path inside it. The error means the address leads nowhere. Linters and bundlers word it differently, and each message tells you a different half of what you need.

How it is reported

A file with one misspelt reference, Ordr for Order:

paths:
  /orders:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Ordr"
components:
  schemas:
    Order:
      type: object

A linter names the target that is missing, and the line of the reference:

$ apigit lint broken-ref.yaml
  18:25  error  invalid-ref            '#/components/schemas/Ordr' does not exist  (paths./orders.get.responses.200.content.application/json.schema.items.$ref)
  21:11  warn   oas3-unused-component  Potentially unused component has been detected.  (components.schemas.Order)

The second finding is the other half of the same mistake: Order exists and nothing refers to it. An unused component right next to a broken reference is almost always the intended target.

A bundler names the place of the reference, as a JSON Pointer:

$ apigit bundle broken-ref.yaml
error: bundle failed: Can't resolve $ref at #/paths/~1orders/get/responses/200/content/application~1json/schema/items

~1 is how a JSON Pointer writes a / inside one segment (and ~0 a ~), so ~1orders is the path /orders and application~1json is application/json. The message says where the reference is, not what it points to: open that place and read the $ref.

The usual causes

CauseExampleFix
A typo in the name#/components/schemas/OrdrCorrect it; look for an unused component with a similar name
The wrong section#/components/schemas/Limit for a parameterParameters live under #/components/parameters/
Case#/components/schemas/orderNames are case sensitive
A file that moved$ref: "./schemas/order.yaml" after a renameRelative paths start at the file that contains the $ref, not at the root document
A missing escape#/paths//orders/getWrite #/paths/~1orders/get

In a multi-file description

A relative $ref is resolved from the file it is written in (in OpenAPI 3.1, from the schema's $id when it has one). ./common.yaml inside schemas/order.yaml means schemas/common.yaml. After moving files, lint the root document first: the linter lists every broken reference with its line, where the bundler stops at the first one it cannot follow.

In CI, lint with a failing severity of error so a broken reference stops the merge:

$ apigit lint --format github-actions openapi.yaml
::error file=openapi.yaml,line=18,col=25,title=invalid-ref::'#/components/schemas/Ordr' does not exist

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish