From 19cafc6a6b7872bfd00f6dc8dbfd384e06d92631 Mon Sep 17 00:00:00 2001
From: Aditya Singh <your_email>
Date: Sun, 21 Dec 2025 21:53:46 +0530
Subject: [PATCH] feat: improve generate fromTemplate error messages

---
 .changeset/nasty-cougars-invent.md        |  5 ++
 src/domains/services/generator.service.ts | 60 +++++++++++++++++++++--
 2 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/nasty-cougars-invent.md

diff --git a/.changeset/nasty-cougars-invent.md b/.changeset/nasty-cougars-invent.md
new file mode 100644
index 00000000..d741c732
--- /dev/null
+++ b/.changeset/nasty-cougars-invent.md
@@ -0,0 +1,5 @@
+---
+"@asyncapi/cli": patch
+---
+
+Improve error messages when `generate fromTemplate` fails due to missing or incompatible templates.
diff --git a/src/domains/services/generator.service.ts b/src/domains/services/generator.service.ts
index ec4f0426..cb006de0 100644
--- a/src/domains/services/generator.service.ts
+++ b/src/domains/services/generator.service.ts
@@ -93,11 +93,63 @@ export class GeneratorService extends BaseService {
       });
     } catch (err: any) {
       s.stop('Generation failed');
-      return this.createErrorResult(err.message, err.diagnostics);
+
+      let enhancedMessage = err.message;
+
+      // Template not found (404 error)
+      if (
+        err.message.includes('404 Not Found') ||
+        err.message.includes('Installation failed')
+      ) {
+        enhancedMessage = `Template '${template}' not found in npm registry.
+
+The template you specified does not exist. This might be because:
+  • The template name is misspelled
+  • The template doesn't exist in the npm registry
+  • You need to use the full package name (e.g., @asyncapi/html-template)
+
+Popular templates: @asyncapi/html-template, @asyncapi/markdown-template, @asyncapi/nodejs-template`;
+      } else if (err.message.includes('not compatible with')) {
+        // Template version incompatibility
+        enhancedMessage = `${err.message}
+
+The template you're using is not compatible with your AsyncAPI document version or generator version.
+
+Possible solutions:
+  • Update the template to a newer version
+  • Use a different template that supports your AsyncAPI version
+  • Check template documentation for compatibility information
+
+Template compatibility info:
+  https://www.asyncapi.com/docs/tools/generator/versioning`;
+      } else if (
+        // Template structure/file not found
+        err.message.includes('ENOENT') &&
+        err.message.includes('template')
+      ) {
+        enhancedMessage = `Template '${template}' installation failed or is corrupted.
+
+This usually happens when:
+  • The package name is missing the scope (use @asyncapi/html-template instead of html-template)
+  • The template was partially downloaded but is incomplete
+  • The template package doesn't follow AsyncAPI template structure`;
+      } else if (
+        // Network/connection errors
+        err.message.includes('ENOTFOUND') ||
+        err.message.includes('ETIMEDOUT') ||
+        err.message.includes('network')
+      ) {
+        enhancedMessage = `Failed to download template due to network issues.
+
+Possible causes:
+  • No internet connection
+  • Firewall blocking npm registry access
+  • npm registry is temporarily unavailable`;
+      }
+
+      return this.createErrorResult(enhancedMessage, err.diagnostics);
     }
-    s.stop(
-      this.getGenerationSuccessMessage(output),
-    );
+    s.stop(this.getGenerationSuccessMessage(output));
 
     return this.createSuccessResult({
       success: true,