What this error means
When you run npx swagger-cli validate openapi.yaml, the underlying parser dereferences every $ref. A $ref fragment is a JSON Pointer, and the parser resolves it one slash-separated token at a time: #/components/schemas/User means "find components, inside it schemas, inside that User". The moment a token has no matching key, resolution stops and you get:
Error resolving $ref pointer "openapi.yaml#/definitions/User".
Token "definitions" does not exist.The named token is the useful part. It tells you exactly which segment failed, so you know whether the whole section is missing (definitions) or just the final target (User).
Why swagger-parser emits it
- Swagger 2.0 pointer in a 3.x document.
#/definitions/Userwas correct in 2.0; OpenAPI 3.x moved schemas to#/components/schemas/User. Converted specs often carry old pointers. - Typo or case mismatch in the final token. Pointers are case-sensitive, so
#/components/schemas/userwill not findUser. - The target was renamed or deleted while the referencing operation kept the old name.
openapi: 3.0.3
info:
title: Example API
version: "1.0"
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/definitions/User' # Swagger 2.0 location
components:
schemas:
User:
type: object
properties:
id:
type: string schema:
$ref: '#/components/schemas/User'One find-and-replace usually clears a converted spec: #/definitions/ becomes #/components/schemas/. Do the same for the other 2.0 sections if they appear: #/parameters/ becomes #/components/parameters/ and #/responses/ becomes #/components/responses/.
How to catch it earlier
Dangling pointers appear whenever schemas get renamed, so the cheap defense is validating on every change rather than at release time. The free OpenAPI validator resolves all refs and lists every unresolvable pointer at once, which beats swagger-cli's stop-at-first-failure behavior when a rename broke ten refs. Pair it with the OpenAPI linter in CI and a broken pointer never reaches a consumer. The blog guide to common OpenAPI validation errors covers the related case mismatch failure in more depth.
Frequently asked questions
What does "Token" mean here?
One slash-separated segment of the JSON Pointer. For #/components/schemas/User the tokens are components, schemas, and User, resolved in that order. The error names the first one that failed.
Why Token "definitions" in an OpenAPI 3 spec?
#/definitions/ is the Swagger 2.0 schema location. OpenAPI 3.x has no top-level definitions key, so that first token fails immediately. Point the ref at #/components/schemas/ instead.
The schema exists. Why is it not found?
Check the case: pointers are case-sensitive. Then check for stray whitespace, and for ~ or / in key names, which must be escaped as ~0 and ~1 inside a pointer.
Does this happen with external file refs too?
Yes. With ./schemas.yaml#/User the parser loads the file first, then walks the fragment. A loadable file with a bad fragment produces the same message, with the failing token taken from the fragment.