[BUG] CLI fails with misleading error when AsyncAPI YAML contains multiple documents
- Dominant language
- TypeScript
- Stars
- 272
- Forks
- 375
- Avg merge
- 3h 22m
- Merged PRs (30d)
- 8
Description
### Describe the bug.
When an AsyncAPI file contains **multiple YAML documents** (separated by `---`), the AsyncAPI CLI fails with a **low-level and misleading parser error** instead of explicitly detecting and rejecting the condition.
While AsyncAPI itself supports only a single document, **multi-document YAML is valid YAML** and commonly appears in real-world workflows. The CLI should therefore fail **explicitly and clearly**, rather than falling into an incorrect parsing code path.
---
## Why multiple YAML documents appear in practice
Multi-document YAML is widely used and often introduced unintentionally:
- Common in **Kubernetes and DevOps** configurations
- Users may **merge or concatenate YAML files**
- Tooling or generators may emit multiple documents by default
- Copy–paste workflows may leave `---` separators behind
- Users may comment out one document but leave the separator
Even if AsyncAPI does not support multi-document files, users reasonably expect the CLI to **detect and clearly reject** this case.
### Expected behavior
When an AsyncAPI file contains multiple YAML documents, the CLI should:
- Detect that multiple YAML documents are present
- Fail early during validation
- Return a clear, user-facing error explaining that only a single AsyncAPI document is supported
Example expected output:
```text
Error: AsyncAPI files with multiple YAML documents are not supported.
```
### Screenshots
### How to Reproduce
1. Create an AsyncAPI file containing multiple YAML documents:
```yaml
asyncapi: '2.6.0'
info:
title: Test API
version: '1.0.0'
channels: {}
---
asyncapi: '2.6.0'
info:
title: Second Doc
version: '1.0.0'
channels: {}
```
2. Run the AsyncAPI CLI:
```
asyncapi generate fromTemplate asyncapi.yaml ./test-template --no-interactive
```
3. Observe the CLI output.
### 🖥️ Device Information [optional]
- Operating System (OS):Windows(WSL)
- Browser:
- Browser Version:
### 👀 Have you checked for similar open issues?
- [x] I checked and didn't find similar issue
### 🏢 Have you read the Contributing Guidelines?
- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)
### Are you willing to work on this issue ?
Yes I am willing to submit a PR!
Contributor guide
Assessment
This issue has not been assessed yet.