From 17f11f7840972f2dd00c252e9b3fd802ca044969 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sun, 29 Mar 2026 11:04:06 +0000
Subject: [PATCH] fix(cli): improve error message for zero-duration composition
 renders

When a composition had zero duration (empty GSAP timeline, no
data-duration), Docker render hung for 45s then showed the misleading
hint "Check Docker is running" even though Docker was fine. Now
detects the __hf-not-ready error and suggests adding data-duration or
GSAP tweens instead.

Reproducer:
  # Create composition with empty timeline and no data-duration
  npx hyperframes render --docker --output out.mp4
  # Was: "Check Docker is running: docker info"
  # Now: "Composition may have zero duration. Add data-duration..."
---
 packages/cli/src/commands/render.ts | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index 71f1d919..c1587564 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -256,7 +256,13 @@ async function renderDocker(
     });
     await producer.executeRenderJob(job, projectDir, outputPath);
   } catch (error: unknown) {
-    handleRenderError(error, options, startTime, true, "Check Docker is running: docker info");
+    handleRenderError(
+      error,
+      options,
+      startTime,
+      true,
+      renderHintForError(error, "Check Docker is running: docker info"),
+    );
   }
 
   const elapsed = Date.now() - startTime;
@@ -297,7 +303,13 @@ async function renderLocal(
   try {
     await producer.executeRenderJob(job, projectDir, outputPath, onProgress);
   } catch (error: unknown) {
-    handleRenderError(error, options, startTime, false, "Try --docker for containerized rendering");
+    handleRenderError(
+      error,
+      options,
+      startTime,
+      false,
+      renderHintForError(error, "Try --docker for containerized rendering"),
+    );
   }
 
   const elapsed = Date.now() - startTime;
@@ -312,6 +324,14 @@ function getMemorySnapshot() {
   };
 }
 
+function renderHintForError(error: unknown, fallback: string): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("__hf not ready")) {
+    return "Composition may have zero duration. Add data-duration to the root element or ensure the GSAP timeline has tweens.";
+  }
+  return fallback;
+}
+
 function handleRenderError(
   error: unknown,
   options: RenderOptions,