asyncapi / asyncapi/cli

[BUG] CLI fails with misleading error when AsyncAPI YAML contains multiple documents

Open
#1,997 4 comments 0 reactions 0 assignees View on GitHub
bug
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

Image

### 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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.