Filtering by tags results in error

[mkeyy0]

Description

When I add filters by tag in the config, it results in an error.
Interesting that when I set orphans as true, the error doesn't happen, but unused types are generated

Error:

[2026-04-01T13:21:02.418Z] Error: Reference not found: #/components/parameters/petId
Stack:
Error: Reference not found: #/components/parameters/petId
    at resolveRef (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/shared/dist/index.mjs:1901:42)
    at Context.resolveRef (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/shared/dist/index.mjs:2345:10)
    at Context.dereference (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/shared/dist/index.mjs:2297:25)
    at parametersArrayToObject$1 (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/shared/dist/index.mjs:6434:62)
    at parseV3_0_X (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/shared/dist/index.mjs:6687:17)
    at Module.parseOpenApiSpec (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/shared/dist/index.mjs:8436:3)
    at createClient$1 (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/openapi-ts/dist/src-onOyaUFS.mjs:151:19)
    at async eval (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/openapi-ts/dist/src-onOyaUFS.mjs:215:12)
    at async Module.createClient (file:///home/projects/hey-api-example-u8nlwzgc/node_modules/@hey-api/openapi-ts/dist/src-onOyaUFS.mjs:213:21)

Reproducible example or configuration

https://stackblitz.com/edit/hey-api-example-u8nlwzgc?file=openapi-ts.config.ts

Config:

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi.yaml',
  output: {
    path: './src/client',
    postProcess: ['prettier', 'eslint'],
  },
  parser: {
    filters: {
      tags: { include: ['pets'] },
      orphans: false,
    },
  },
  plugins: [
    '@hey-api/schemas',
    {
      name: '@hey-api/transformers',
    },
    {
      enums: 'javascript',
      name: '@hey-api/typescript',
    },
    {
      name: '@hey-api/sdk',
    },
  ],
});

OpenAPI specification (optional)

openapi: 3.0.0
info:
  description: API for managing petstore data
  title: Petstore API
  version: 1.0.0
servers:
  - url: /
paths:

  /api/v1/pets:
    get:
      description: Retrieves a paginated list of pets
      operationId: listPets
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/xPaginationCursorOnly'
        - $ref: '#/components/parameters/isArchived'
        - $ref: '#/components/parameters/speciesFilter'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  next:
                    description: URL for next page of results or just the cursor value if X-Pagination-Cursor-Only header was set to 'true'. Default behavior (when header is omitted) is to return full URLs.
                    nullable: true
                    type: string
                  previous:
                    description: URL for previous page of results or just the cursor value if X-Pagination-Cursor-Only header was set to 'true'. Default behavior (when header is omitted) is to return full URLs.
                    nullable: true
                    type: string
                  results:
                    items:
                      $ref: '#/components/schemas/Pet'
                    type: array
                required:
                  - results
                  - previous
                  - next
                type: object
          description: Successful response
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: List all pets with pagination
      tags:
        - pets
    post:
      description: Creates a new pet
      operationId: createPet
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetInput'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
          description: Created
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Create a new pet
      tags:
        - pets

  /api/v1/pets/{petId}:
    parameters:
      - $ref: '#/components/parameters/petId'
    get:
      description: Retrieves details of a specific pet
      operationId: getPet
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
          description: Successful response
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Get a pet by ID
      tags:
        - pets
    put:
      description: Updates an existing pet's details
      operationId: updatePet
      parameters:
        - $ref: '#/components/parameters/xIfUnmodifiedSince'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetUpdate'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
          description: Successful response
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "412":
          $ref: '#/components/responses/PreconditionFailed'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Update a pet
      tags:
        - pets
    delete:
      description: Deletes an existing pet
      operationId: deletePet
      responses:
        "204":
          description: Successfully deleted
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          $ref: '#/components/responses/Conflict'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Delete a pet
      tags:
        - pets

  /api/v1/owners:
    get:
      description: Retrieves a paginated list of owners
      operationId: listOwners
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/xPaginationCursorOnly'
        - $ref: '#/components/parameters/isArchived'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  next:
                    nullable: true
                    type: string
                  previous:
                    nullable: true
                    type: string
                  results:
                    items:
                      $ref: '#/components/schemas/Owner'
                    type: array
                required:
                  - results
                  - previous
                  - next
                type: object
          description: Successful response
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: List all owners with pagination
      tags:
        - owners
    post:
      description: Creates a new owner
      operationId: createOwner
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnerInput'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
          description: Created
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Create a new owner
      tags:
        - owners

  /api/v1/owners/{ownerId}:
    parameters:
      - $ref: '#/components/parameters/ownerId'
    get:
      description: Retrieves details of a specific owner
      operationId: getOwner
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
          description: Successful response
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Get an owner by ID
      tags:
        - owners
    put:
      description: Updates an existing owner's details
      operationId: updateOwner
      parameters:
        - $ref: '#/components/parameters/xIfUnmodifiedSince'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnerUpdate'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
          description: Successful response
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "412":
          $ref: '#/components/responses/PreconditionFailed'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Update an owner
      tags:
        - owners
    delete:
      description: Deletes an existing owner. Cannot delete if they still have active pets.
      operationId: deleteOwner
      responses:
        "204":
          description: Successfully deleted
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Cannot delete owner with active pets
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: Delete an owner
      tags:
        - owners

  /api/v1/owners/{ownerId}/pets:
    parameters:
      - $ref: '#/components/parameters/ownerId'
    get:
      description: Retrieves a paginated list of pets belonging to a specific owner
      operationId: listOwnerPets
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/xPaginationCursorOnly'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  next:
                    nullable: true
                    type: string
                  previous:
                    nullable: true
                    type: string
                  results:
                    items:
                      $ref: '#/components/schemas/Pet'
                    type: array
                required:
                  - results
                  - previous
                  - next
                type: object
          description: Successful response
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
        - cookieAuth: []
        - bearerAuth: []
      summary: List pets for a specific owner
      tags:
        - owners
        - pets

components:
  parameters:

    petId:
      in: path
      name: petId
      required: true
      schema:
        format: uuid
        type: string

    ownerId:
      in: path
      name: ownerId
      required: true
      schema:
        format: uuid
        type: string

    cursor:
      description: Pagination cursor (UUID format)
      in: query
      name: cursor
      schema:
        format: uuid
        type: string

    isArchived:
      description: Filter by archive status. If not specified, returns only non-archived items
      in: query
      name: is_archived
      required: false
      schema:
        type: boolean

    speciesFilter:
      description: Filter by species
      in: query
      name: species
      required: false
      schema:
        $ref: '#/components/schemas/PetSpecies'

    xIfUnmodifiedSince:
      description: |
        Only perform the operation if the resource has not been modified since the specified date.
        If the resource has been modified, the server will return a 412 Precondition Failed response.
        Supports both HTTP-date format (RFC 1123) and ISO 8601 format (RFC 3339).
      examples:
        http_date:
          summary: HTTP date format
          value: Fri, 11 Jul 2025 07:28:00 GMT
        iso_8601:
          summary: ISO 8601 format
          value: "2025-07-25T12:01:20+02:00"
        iso_8601_utc:
          summary: ISO 8601 UTC format
          value: "2025-07-25T10:01:20Z"
      in: header
      name: If-Unmodified-Since
      required: false
      schema:
        description: Date in HTTP-date format (RFC 1123) or ISO 8601 format (RFC 3339)
        example: Fri, 11 Jul 2025 07:28:00 GMT
        type: string

    xPaginationCursorOnly:
      description: When set to any non-empty value, pagination links in responses will contain only the cursor value instead of the full URL with all query parameters.
      in: header
      name: X-Pagination-Cursor-Only
      required: false
      schema:
        type: string

  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad request
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource already exists or conflicts with another resource
    InternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal server error
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    PreconditionFailed:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource has been modified after the specified date
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Unauthorized
    UnexpectedError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: An unexpected error occurred.

  schemas:

    ID:
      description: The entity ID as UUID version 7
      format: uuid
      type: string

    IsArchived:
      default: false
      description: Whether the entity is archived
      type: boolean

    IsTest:
      default: false
      description: Whether the entity is a test entity
      type: boolean

    TimestampFields:
      description: Common timestamp fields for entity objects
      properties:
        created_at:
          description: Creation timestamp
          format: date-time
          type: string
        updated_at:
          description: Last update timestamp
          format: date-time
          type: string
      required:
        - created_at
        - updated_at
      type: object

    Error:
      description: Represents error object
      properties:
        code:
          enum:
            - authentication_failed
            - bad_request
            - duplicate_record
            - internal_server_error
            - not_found
            - validation_failed
            - precondition_failed
          type: string
        details:
          additionalProperties:
            items:
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
              type: object
            type: array
          type: object
        message:
          type: string
      required:
        - code
        - message
      type: object

    PetSpecies:
      description: Species of the pet
      enum:
        - dog
        - cat
        - bird
        - rabbit
        - fish
        - other
      type: string

    PetStatus:
      description: Adoption status of the pet
      enum:
        - available
        - adopted
        - pending
      type: string

    Pet:
      allOf:
        - $ref: '#/components/schemas/TimestampFields'
        - properties:
            age_years:
              description: Age of the pet in years
              format: float
              minimum: 0
              nullable: true
              type: number
            breed:
              description: Breed of the pet
              maxLength: 100
              nullable: true
              type: string
            id:
              $ref: '#/components/schemas/ID'
            is_archived:
              $ref: '#/components/schemas/IsArchived'
            is_test:
              $ref: '#/components/schemas/IsTest'
            name:
              maxLength: 100
              minLength: 1
              type: string
            object_type:
              default: pet
              description: Constant identifier for this object type
              enum:
                - pet
              type: string
            owner_id:
              format: uuid
              nullable: true
              type: string
            species:
              $ref: '#/components/schemas/PetSpecies'
            status:
              $ref: '#/components/schemas/PetStatus'
            tags:
              items:
                maxLength: 50
                type: string
              maxItems: 20
              type: array
            weight_kg:
              description: Weight of the pet in kilograms
              format: float
              minimum: 0
              nullable: true
              type: number
          required:
            - id
            - name
            - species
            - status
            - owner_id
            - breed
            - age_years
            - weight_kg
            - tags
            - is_archived
            - is_test
            - object_type
          type: object
      type: object

    PetInput:
      properties:
        age_years:
          format: float
          minimum: 0
          nullable: true
          type: number
        breed:
          maxLength: 100
          nullable: true
          type: string
        is_test:
          $ref: '#/components/schemas/IsTest'
        name:
          maxLength: 100
          minLength: 1
          type: string
        owner_id:
          format: uuid
          nullable: true
          type: string
        species:
          $ref: '#/components/schemas/PetSpecies'
        tags:
          items:
            maxLength: 50
            type: string
          maxItems: 20
          type: array
        weight_kg:
          format: float
          minimum: 0
          nullable: true
          type: number
      required:
        - name
        - species
      type: object

    PetUpdate:
      properties:
        age_years:
          format: float
          minimum: 0
          nullable: true
          type: number
        breed:
          maxLength: 100
          nullable: true
          type: string
        is_archived:
          $ref: '#/components/schemas/IsArchived'
        name:
          maxLength: 100
          minLength: 1
          type: string
        owner_id:
          format: uuid
          nullable: true
          type: string
        status:
          $ref: '#/components/schemas/PetStatus'
        tags:
          items:
            maxLength: 50
            type: string
          maxItems: 20
          type: array
        weight_kg:
          format: float
          minimum: 0
          nullable: true
          type: number
      required:
        - name
        - species
        - status
        - owner_id
        - breed
        - age_years
        - weight_kg
        - tags
        - is_archived
      type: object

    Owner:
      allOf:
        - $ref: '#/components/schemas/TimestampFields'
        - properties:
            email:
              format: email
              type: string
            full_name:
              maxLength: 200
              minLength: 1
              type: string
            id:
              $ref: '#/components/schemas/ID'
            is_archived:
              $ref: '#/components/schemas/IsArchived'
            is_test:
              $ref: '#/components/schemas/IsTest'
            object_type:
              default: owner
              description: Constant identifier for this object type
              enum:
                - owner
              type: string
            pets:
              description: Use GET /api/v1/owners/{ownerId}/pets to get a list of pets
              properties:
                total_count:
                  type: integer
              required:
                - total_count
              type: object
            phone:
              maxLength: 30
              nullable: true
              type: string
          required:
            - id
            - full_name
            - email
            - phone
            - pets
            - is_archived
            - is_test
            - object_type
          type: object
      type: object

    OwnerInput:
      properties:
        email:
          format: email
          type: string
        full_name:
          maxLength: 200
          minLength: 1
          type: string
        is_test:
          $ref: '#/components/schemas/IsTest'
        phone:
          maxLength: 30
          nullable: true
          type: string
      required:
        - full_name
        - email
      type: object

    OwnerUpdate:
      properties:
        email:
          format: email
          type: string
        full_name:
          maxLength: 200
          minLength: 1
          type: string
        is_archived:
          $ref: '#/components/schemas/IsArchived'
        phone:
          maxLength: 30
          nullable: true
          type: string
      required:
        - full_name
        - email
        - phone
        - is_archived
      type: object

  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    cookieAuth:
      in: cookie
      name: access-token
      type: apiKey

System information (optional)

@hey-api/openapi-ts version: "0.94.5"

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• hey-api-example-u8nlwzgc (Open reproduction)

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[mkeyy0]

@dosubot, what additional info is needed?

[dosubot]

To help diagnose this more effectively, it would be useful to have:

1. The exact error message/stack trace — could you paste the full error output you see when running the codegen with tag filters?
2. Your openapi-ts.config.ts — the StackBlitz link may not be accessible to everyone, so pasting the relevant config inline would help.
3. The version of @hey-api/openapi-ts you're using.
4. A minimal snippet of your OpenAPI spec (or at least the relevant operation/schema structure) — specifically the parts related to the tags you're filtering on.

The error and stack trace in particular would go a long way toward pinpointing where things break during orphan resolution.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}
  

[mkeyy0]

@dosu Added all required info

[dosubot]

Thanks for adding the details! Based on the error and your description, here's what's happening:

The error Reference not found: #/components/parameters/petId occurs because when you use parser.filters.tags, the orphans option defaults to false. This causes the parser to strip out components it considers "orphaned" — but it appears to be incorrectly removing #/components/parameters/petId even though it's still referenced by operations that match your tag filter. When the parser later tries to resolve that $ref, the component is already gone, hence the error.

The stack trace confirms this — the failure is in resolveRef called from parametersArrayToObject, meaning it's trying to dereference a parameter $ref on a filtered-in operation, but the referenced parameter component was already removed during orphan cleanup.

This looks like a bug in the orphan detection logic: it should be preserving any component that is transitively referenced by operations surviving the tag filter, but it isn't.

Workaround for now: As you discovered, setting orphans: true avoids the crash (at the cost of extra unused types in the output).

I'd recommend keeping this issue open for the maintainers to look into the orphan resolution logic in @hey-api/shared.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}
  

[mkeyy0]

@dosu could you remove the "needs info" label from the PR, as I provided everything needed

[dosubot]

Sorry, I don't have the ability to modify labels on issues or PRs — I can only help with answering questions and providing information. A maintainer will need to remove the "needs info" label. Since you've added all the requested details, they should be able to update it when they review the issue.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}