@hey-api/openapi-ts is stricter than most tools that produced your spec. Validate the spec here, see the exact schema problems that break client generation, and fix them before running codegen again.
Many tools that produce OpenAPI specs (framework exporters, gateways, converters) are permissive, while hey-api reads the schema strictly to generate accurate TypeScript types and Zod validation. The most common gap: a field appears in the required array but its schema says it can be null — or the reverse. Loose tools shrug; strict codegen fails or generates types that reject real responses. The fix is always in the spec, and a strict validator shows you exactly where.
A property is listed in required but its schema allows null (or it's nullable in responses that the spec marks required). Generated types and Zod schemas then reject real API responses at runtime. Decide per field: truly required → remove nullability; genuinely nullable → model it explicitly and drop it from required.
OpenAPI 3.0 uses nullable: true; 3.1 uses type: ["string", "null"]. Specs that declare openapi: 3.1.0 but still use 3.0-style nullable (or vice versa) confuse strict parsers. Pick one version and use its null syntax consistently.
A $ref points to a component that doesn't exist (typo, deleted schema, or an external file that isn't bundled). Codegen has nothing to generate a type from and aborts. Large third-party specs — chat platforms, payment APIs — are full of these.
Response bodies declared with no schema, type: object with no properties, or conflicting oneOf/anyOf branches. hey-api either produces unknown everywhere or fails outright. Tighten the schema so the generator has something concrete to type.
npx @hey-api/openapi-ts -i openapi.yaml -o src/clientTell us which generator or importer your spec has to satisfy — the most-requested target gets first-class support next.
Validate your spec, fix the flagged lines, and generate your hey-api client — all free, no account needed.
Validate My Spec Now