openapi-generator "Could not resolve reference ... $ref" in CI

By Kaveh Alemi·Latchkey

OpenAPI Generator resolves every $ref in the spec before generating. When a $ref points at a missing component, a wrong JSON pointer, or an unreachable external file, it reports it could not resolve the reference and fails.

What this error means

openapi-generator-cli fails with "Could not resolve reference because of: Could not resolve pointer: /components/schemas/<Name> does not exist" or "unable to resolve" for an external file ref.

Exception in thread "main" org.openapitools.codegen.SpecValidationException: ...
Could not resolve reference because of: Could not resolve pointer:
/components/schemas/User does not exist in document

Common causes

A $ref points at a component that does not exist

The JSON pointer (for example #/components/schemas/User) names a schema that is misspelled or absent in the document.

An external file $ref is unreachable in CI

A $ref to another file or URL cannot be resolved because the file was not checked out at that relative path, or the URL is unreachable from the runner.

How to fix it

Fix the pointer or add the missing component

1. Read the pointer in the error and check components/schemas for it.
2. Correct the $ref path or define the missing schema.
3. Re-run generation to confirm the reference resolves.

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string }

Bundle external refs before generating

Resolve split files into one document so the generator never has to fetch external refs in CI.

npx @redocly/cli bundle openapi.yaml -o openapi.bundled.yaml
openapi-generator-cli generate -i openapi.bundled.yaml -g typescript-axios -o ./client

How to prevent it

• Validate the spec (openapi-generator-cli validate) before generation.
• Bundle multi-file specs into one document for CI.
• Keep $ref pointers in sync with the component names you define.

Frequently asked questions

Related guides

References

• GitHub Actions documentation