**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.

```text
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.
2. 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.
3. Validate the whole spec with a resolver:
   ```
   npx @apidevtools/swagger-cli validate openapi/openapi.yaml
   ```
   Expected: `openapi/openapi.yaml is valid`.
4. 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.
5. 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