openapi generator "cannot resolve reference #/components/schemas"

TL;DR

Point the dangling ref at a schema name that exists under components/schemas, or add the missing schema, then rerun the generator. openapi-generator resolves every reference at codegen time and aborts on the first one it cannot find. Lint the spec first so you fix all dangling refs in one pass instead of one at a time.

The error

cannot resolve reference #/components/schemas

Steps

1. Lint the spec to list every broken reference: npx @redocly/cli lint openapi.yaml. Expected: the output names each file and line with an unresolvable ref.
2. Open the spec at the reported line and copy the schema name from the ref. Expected: you have the exact name the ref asks for, for example the part after #/components/schemas/.
3. Check whether that exact name exists under the schemas: section of components. Names are case-sensitive. Expected: you confirm the name is missing, misspelled, or was renamed.
4. Fix it one of two ways: rename the ref to the correct schema name, or add the missing schema definition under components/schemas. Expected: every ref in the spec points at a defined schema.
5. Re-lint: npx @redocly/cli lint openapi.yaml. Expected: no "cannot resolve" findings remain.
6. Rerun codegen: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g python -o out. Expected: the command exits 0 and the output directory contains generated model files.

Use this when

• The generate command fails with a "cannot resolve reference" message.
• The failing ref starts with #/components/schemas/.
• The failure appeared after a schema rename, deletion, or spec merge.

Not for this skill when

• The error is about parameters, responses, or external file refs - the fix location differs even though the shape is similar.
• The generator fails on template or language-specific errors with no reference message.
• You are hand-writing a client rather than generating one.

Variant phrasings

could not resolve reference

Some generator versions and wrappers print "could not resolve reference" with the same #/components/schemas/ path. Same fix.

failed to resolve pointer

Older openapi-generator releases phrase it as "failed to resolve pointer" for the same dangling schema problem. Same fix.

unresolved ref in spec

Spec linters describe the same condition as an unresolved ref. If the linter flags it, the generator will fail on it too.

Why it happens

openapi-generator builds an in-memory model of the whole spec before emitting code, so every ref must resolve. Refs dangle most often after a schema is renamed in one place but not in the refs that point at it, after a merge conflict drops a schema definition, or after splitting a spec into multiple files without updating relative paths.

Edge cases

• Case sensitivity: Widget and widget are different schemas. The linter catches this; eyeballing often misses it.
• Multi-file specs: a ref into another file needs that file present at the path the generator runs from. Run codegen from the repo root or pass absolute input paths.
• The generator caches resolved specs in some setups. If the fix does not seem to take, clear the output directory and rerun rather than editing generated files.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_AiX-Fq5lLd22PZ79MxpVAw