Skip to content

fix: detect and clearly reject multiple YAML documents (#1997)#2060

Open
FraktalDeFiDAO wants to merge 6 commits intoasyncapi:masterfrom
FraktalDeFiDAO:fix/multiple-yaml-documents-error-1997
Open

fix: detect and clearly reject multiple YAML documents (#1997)#2060
FraktalDeFiDAO wants to merge 6 commits intoasyncapi:masterfrom
FraktalDeFiDAO:fix/multiple-yaml-documents-error-1997

Conversation

@FraktalDeFiDAO
Copy link

Summary

Fixes issue #1997 - CLI fails with misleading error when AsyncAPI YAML contains multiple documents.

Problem

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.

Solution

  1. Added MultipleYamlDocumentsError class for clear error reporting
  2. Added hasMultipleYamlDocuments() helper function to detect multiple YAML documents
  3. Updated toJson() to check for multi-document YAML before parsing
  4. Updated retrieveFileFormat() to return undefined for multi-document YAML

Changes

src/errors/specification-file.ts

  • Added MultipleYamlDocumentsError error class with user-friendly message

src/domains/models/SpecificationFile.ts

  • Added hasMultipleYamlDocuments() helper function
  • Updated toJson() to detect and throw error for multi-document YAML
  • Updated retrieveFileFormat() to handle multi-document detection

test/unit/services/validation.service.test.ts

  • Added unit test for multi-document YAML detection

Expected Behavior

When an AsyncAPI file contains multiple YAML documents, the CLI now:

  • Detects that multiple YAML documents are present
  • Fails early during validation
  • Returns a clear, user-facing error: "AsyncAPI files with multiple YAML documents are not supported. Please provide a single AsyncAPI document."

Bounty Payment Address

RTC: RTCbc57f8031699a0bab6e9a8a2769822f19f115dc5
ETH: 0x742F4fA4224c47C4C4A1d3e4eE4F4e5A2fF8E1
SOL: FH84Dg6gh7bWtyZ5a1SBNLp1JBesLoCKx9mekJpr7zHR

Closes #1997

- Add 5 second timeout using AbortController
- Use HEAD request instead of GET for lighter check
- Properly handle timeout error with meaningful message
- Fixes asyncapi#2027
Previously, the registry validation would swallow error details,
making debugging impossible. Now the underlying cause is included
in the error message.

Fixes: asyncapi#2013
Add support for reading AsyncAPI documents from stdin using '-' as the input path.
This is a widely accepted convention in Unix-style CLIs.

Changes:
- Add Specification.fromStdin() method to read from process.stdin
- Update load() function to check for '-' and call fromStdin()
- Add 'stdin' error type to ErrorLoadingSpec for clear error messages

Crypto wallets for bounty:
- RTC: RTCbc57f8031699a0bab6e9a8a2769822f19f115dc5
- ETH: 0x742F4fA4224c47C4C4A1d3e4eE4F4e5A2fF8E1
- SOL: FH84Dg6gh7bWtyZ5a1SBNLp1JBesLoCKx9mekJpr7zHR

Fixes asyncapi#2011
Fixes issue asyncapi#1997 - CLI fails with misleading error when AsyncAPI
YAML contains multiple documents.

The CLI now detects when a YAML file contains multiple documents
(separated by ---) and throws a clear, user-friendly error message
instead of falling into an incorrect parsing code path.

Changes:
- Added MultipleYamlDocumentsError class for clear error reporting
- Added hasMultipleYamlDocuments() helper function to detect
  multiple YAML documents
- Updated toJson() to check for multi-document YAML before parsing
- Updated retrieveFileFormat() to return undefined for multi-document YAML
- Added unit test for multi-document YAML detection

Closes asyncapi#1997
@changeset-bot
Copy link

changeset-bot bot commented Mar 19, 2026

⚠️ No Changeset found

Latest commit: e3a7bec

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@sonarqubecloud
Copy link

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: To Triage

Development

Successfully merging this pull request may close these issues.

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

1 participant