From 72cb2bd9b6dce1dac1b350810f8575737ef1b36c Mon Sep 17 00:00:00 2001 From: wonjang <48057918+wonjangcloud9@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:11:41 +0000 Subject: [PATCH] fix(cli): a render that failed on a video file says to check the file, not to try Docker (#8083) The generic "Try --docker for containerized rendering" hint was printed under every failed render. When the failure is a video source FFmpeg could not read, a missing file or a 404 URL, a container reads the same source and fails the same way. Those three now get a hint about the file. Co-authored-by: Claude Fable 5.2 --- packages/cli/src/commands/render.ts | 3 +- .../commands/render/sourceFailureHint.test.ts | 52 +++++++++++++++++++ .../src/commands/render/sourceFailureHint.ts | 33 ++++++++++++ 3 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 packages/cli/src/commands/render/sourceFailureHint.test.ts create mode 100644 packages/cli/src/commands/render/sourceFailureHint.ts diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index c1c7aaf2e5..e9a33f131c 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -85,6 +85,7 @@ import { } from "../ui/format.js"; import { warnIfWebmAlphaDropped } from "../utils/webmAlphaCheck.js"; import { renderFailureDiagnostic } from "../ui/renderDiagnostic.js"; +import { sourceFailureHint } from "./render/sourceFailureHint.js"; import { missingPathKind } from "../telemetry/missingPathKind.js"; import { renderProgress, renderMachineProgress } from "../ui/progress.js"; import { @@ -2027,7 +2028,7 @@ function handleRenderError( errorBox(launch.title, shown, launch.remediation); failCommand(); } - errorBox("Render failed", shown, hint); + errorBox("Render failed", shown, sourceFailureHint(error) ?? hint); failCommand(); } diff --git a/packages/cli/src/commands/render/sourceFailureHint.test.ts b/packages/cli/src/commands/render/sourceFailureHint.test.ts new file mode 100644 index 0000000000..ed28870bb5 --- /dev/null +++ b/packages/cli/src/commands/render/sourceFailureHint.test.ts @@ -0,0 +1,52 @@ +import { describe, expect, it } from "vitest"; +import { sourceFailureHint } from "./sourceFailureHint.js"; + +function stageError(code: string, kinds: string[]): Error { + return Object.assign(new Error(`Video extraction failed [${code}; ${kinds.join(",")}]`), { + code, + failures: kinds.map((kind) => ({ kind, count: 1 })), + }); +} + +describe("sourceFailureHint", () => { + it("tells the person to check a file FFmpeg could not read", () => { + const hint = sourceFailureHint(stageError("VIDEO_SOURCE_UNRENDERABLE", ["invalid_media"])); + expect(hint).toContain("ffprobe"); + expect(hint).toContain("still being written"); + expect(hint).not.toContain("--docker"); + }); + + it("names a missing file and a missing URL apart", () => { + expect( + sourceFailureHint(stageError("VIDEO_SOURCE_UNRENDERABLE", ["source_missing"])), + ).toContain("is not there"); + expect( + sourceFailureHint(stageError("VIDEO_SOURCE_UNRENDERABLE", ["download_not_found"])), + ).toContain("404"); + }); + + it("joins the hints when sources failed in different ways", () => { + const hint = sourceFailureHint( + stageError("VIDEO_SOURCE_UNRENDERABLE", ["invalid_media", "source_missing"]), + ); + expect(hint).toContain("ffprobe"); + expect(hint).toContain("is not there"); + }); + + it("finds the stage error behind a wrapping error", () => { + const wrapped = new Error("Render failed", { + cause: stageError("VIDEO_SOURCE_UNRENDERABLE", ["invalid_media"]), + }); + expect(sourceFailureHint(wrapped)).toContain("ffprobe"); + }); + + it("leaves other failures to the generic hint", () => { + expect(sourceFailureHint(new Error("Navigation timeout of 60000 ms exceeded"))).toBeNull(); + expect( + sourceFailureHint(stageError("VIDEO_EXTRACTION_FAILED", ["ffmpeg_transient"])), + ).toBeNull(); + expect( + sourceFailureHint(stageError("VIDEO_SOURCE_UNRENDERABLE", ["invalid_media", "internal"])), + ).toBeNull(); + }); +}); diff --git a/packages/cli/src/commands/render/sourceFailureHint.ts b/packages/cli/src/commands/render/sourceFailureHint.ts new file mode 100644 index 0000000000..e3599bc603 --- /dev/null +++ b/packages/cli/src/commands/render/sourceFailureHint.ts @@ -0,0 +1,33 @@ +/** + * What to do when the render stopped on a video source it could not use. The generic hint is + * "Try --docker", which cannot help: a container reads the same file. + */ +const SOURCE_HINTS: Readonly> = { + invalid_media: + "FFmpeg could not read the file as a video. Check it with `ffprobe `: a file that is still being written, or was cut short, fails this way. Render again once it is complete.", + source_missing: + "The video file is not there. Check the `src` of the