## TL;DR
Validate the AsyncAPI document first, then align the Modelina version with the AsyncAPI version. Generation fails on invalid input or version mismatch far more often than on Modelina bugs.

## Error
```text
Error: failed to generate TypeScript types from asyncapi.yaml
```

## Steps
1. Validate the document: `asyncapi validate asyncapi.yaml` (or the studio validator). Expected: a clean validation, or a concrete schema error to fix first.
2. Check versions: Modelina 1.x/2.x/3.x support different AsyncAPI versions. Match the Modelina major to your document's `asyncapi:` version field. Expected: compatible pair.
3. Simplify the failing construct: deeply nested oneOf/anyOf with discriminators and recursive refs are the usual generation killers. Flatten or name the problematic schema. Expected: the generator gets past the failing message payload.
4. Re-run the Modelina generation for TypeScript. Expected: type files are emitted.

## When to use
- Modelina fails generating TypeScript types
- The AsyncAPI document is new or was just upgraded to a new version
- A docs agent generated the AsyncAPI with version confusion

## When not to use
- The document fails validation (fix the document first)
- You need a different language output (same debugging shape, different generator)
- Generation succeeds but types look wrong (a modeling issue, not a failure)

## Tool compatibility
Modelina 1.x through 3.x with AsyncAPI 2.x and 3.x documents.

### Variant phrasings
### failed to generate after an AsyncAPI 3.0 upgrade
Upgrade Modelina to a 3.x-aware release; older Modelina cannot parse 3.0 documents.

### generation fails on one message only
Isolate that message's payload schema; recursive or unresolvable refs there abort the whole run.

## Why it happens
Modelina parses the full document into a constrained meta-model before rendering. Anything outside the supported subset for your version pair (new spec keywords, exotic composition) fails the parse, and the error surfaces as a generation failure.

## Provenance

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