From 64fa4dade528613d1ebd67ce5fd8088ec57150d6 Mon Sep 17 00:00:00 2001
From: armorbreak001 <contact@agentvote.cc>
Date: Mon, 13 Apr 2026 21:43:53 +0800
Subject: [PATCH 1/2] fix: detect and reject multi-document YAML files with
 clear error (fixes #1997)

When a YAML file contains multiple documents separated by ---,
the parser produces confusing low-level errors. This fix detects
multi-document YAML early in Specification.fromFile() and throws
a clear, user-facing error message.

Also extends ErrorLoadingSpec to support optional customMessage
parameter for more specific error context.

Fixes #1997
---
 src/domains/models/SpecificationFile.ts | 17 +++++++++++++++++
 src/errors/specification-file.ts        |  4 ++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/domains/models/SpecificationFile.ts b/src/domains/models/SpecificationFile.ts
index 5370f6e67..a34d801bd 100644
--- a/src/domains/models/SpecificationFile.ts
+++ b/src/domains/models/SpecificationFile.ts
@@ -86,6 +86,23 @@ export class Specification {
     } catch {
       throw new ErrorLoadingSpec('file', filepath);
     }
+
+    // Detect multi-document YAML (separated by ---) and reject with a clear error.
+    // AsyncAPI only supports single-document YAML files. Multi-doc YAML is valid YAML
+    // but causes confusing low-level parser errors downstream.
+    // See: https://github.com/asyncapi/cli/issues/1997
+    const trimmed = spec.trim();
+    const docSeparators = (trimmed.match(/^---$/gm) || []).length;
+    if (docSeparators > 1) {
+      throw new ErrorLoadingSpec(
+        'file',
+        filepath,
+        `File contains multiple YAML documents (${docSeparators - 1} separators found). ` +
+          `AsyncAPI only supports single-document YAML files. ` +
+          `Please split the file or remove extra \`---\` separators.`,
+      );
+    }
+
     return new Specification(spec, { filepath });
   }
 
diff --git a/src/errors/specification-file.ts b/src/errors/specification-file.ts
index fd64be34d..781c98fbf 100644
--- a/src/errors/specification-file.ts
+++ b/src/errors/specification-file.ts
@@ -37,11 +37,11 @@ export class ErrorLoadingSpec extends Error {
   private readonly errorMessages = {
     default: NO_CONTEXTS_SAVED,
   };
-  constructor(from?: From, param?: string) {
+  constructor(from?: From, param?: string, customMessage?: string) {
     super();
     if (from === 'file') {
       this.name = 'error loading AsyncAPI document from file';
-      this.message = `${param} file does not exist.`;
+      this.message = customMessage ?? `${param} file does not exist.`;
     }
     if (from === 'url') {
       this.name = 'error loading AsyncAPI document from url';

From 3e6604c71d578d57764c70823d6375419bf88c93 Mon Sep 17 00:00:00 2001
From: armorbreak001 <contact@agentvote.cc>
Date: Mon, 13 Apr 2026 22:18:55 +0800
Subject: [PATCH 2/2] fix: also detect multi-doc YAML from URL sources (fixes
 #1997)

Extended multi-document YAML detection to fromURL() in addition
to fromFile(). URLs can also return multi-document YAML content.
---
 src/domains/models/SpecificationFile.ts | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/src/domains/models/SpecificationFile.ts b/src/domains/models/SpecificationFile.ts
index a34d801bd..d77a06de9 100644
--- a/src/domains/models/SpecificationFile.ts
+++ b/src/domains/models/SpecificationFile.ts
@@ -147,7 +147,22 @@ export class Specification {
       throw new ErrorLoadingSpec('url', targetUrl);
     }
 
-    return new Specification((await response?.text()) as string, {
+    const urlSpec = (await response?.text()) as string;
+
+    // Detect multi-document YAML (same check as fromFile)
+    // See: https://github.com/asyncapi/cli/issues/1997
+    const trimmed = urlSpec.trim();
+    const docSeparators = (trimmed.match(/^---$/gm) || []).length;
+    if (docSeparators > 1) {
+      throw new ErrorLoadingSpec(
+        'url',
+        targetUrl,
+        `URL content contains multiple YAML documents (${docSeparators - 1} separators found). ` +
+          `AsyncAPI only supports single-document YAML files.`,
+      );
+    }
+
+    return new Specification(urlSpec, {
       fileURL: targetUrl,
     });
   }