swagger codegen "failed to resolve $ref" in openapi spec

TL;DR: Fix the broken $ref - it points at a file or URL the resolver cannot reach. Open the spec at the reported location, check the relative path from the referencing file (not from the repo root), and confirm the target file exists. Validate the whole spec with a resolver before re-running codegen.

failed to resolve $ref

1. Find the bad reference. The codegen error names the file and the $ref value; cross-check with:

   grep -rn '$ref' openapi/

Expected: the listed $ref values, one of which matches the failing one.

1. Resolve the path by hand: a ref like ./schemas/User.yaml is relative to the file containing it, not to the spec root. Confirm the target file exists at that relative location.
2. Validate the whole spec with a resolver:

   npx @apidevtools/swagger-cli validate openapi/openapi.yaml

Expected: openapi/openapi.yaml is valid.

1. Re-run codegen:

   npx @openapitools/openapi-generator-cli generate -i openapi/openapi.yaml -g python -o out/

Expected: the generator completes and out/ contains the generated client code.

1. For remote refs (http URLs), make sure the machine running the generator can reach them at build time; copy them into the repo if the build runs offline.

Use this when

• swagger-codegen or openapi-generator fails with "failed to resolve $ref"
• A spec that validates in an editor fails at generation time
• You split a spec into multiple files and the refs broke

Not for this skill when

• The error is a schema validation failure, not a resolution failure - the ref resolves but the content is invalid
• The generator fails on an unsupported feature - that is a generator limitation, not a broken ref
• The $ref points at a URL that needs authentication - vendoring the file is the fix, not path edits

Variant phrasings

• "swagger codegen failed to resolve ref"
• "openapi generator cannot resolve reference"
• "failed to resolve $ref openapi"

Why it happens

$ref values are resolved relative to the file that contains them, and resolvers fetch remote refs over the network at generation time. A path that looks right from the repo root, a renamed file, or a URL that is unreachable from the build machine all produce the same "failed to resolve" failure.

Edge cases

• Circular refs can resolve yet still break some generators; check the generator's docs for its circular-reference support.
• In OpenAPI 3.0, sibling keys next to $ref are ignored; put descriptions on the referencing schema or move to 3.1.
• Always use forward slashes in ref paths, even on Windows; backslashes break resolution.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cTnM0IQu0f3k7OxLNcoIWg