"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
| Cause | Example | Fix |
|---|---|---|
| A typo in the name | #/components/schemas/Ordr | Correct it; look for an unused component with a similar name |
| The wrong section | #/components/schemas/Limit for a parameter | Parameters live under #/components/parameters/ |
| Case | #/components/schemas/order | Names are case sensitive |
| A file that moved | $ref: "./schemas/order.yaml" after a rename | Relative paths start at the file that contains the $ref, not at the root document |
| A missing escape | #/paths//orders/get | Write #/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