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 <noreply@anthropic.com>
This commit is contained in:
wonjang
2026-11-18 16:11:41 +00:00
committed by GitHub
co-authored by Claude Fable 5.2
parent 7a63b10d76
commit 72cb2bd9b6
3 changed files with 87 additions and 1 deletions
+2 -1
View File
@@ -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();
}
@@ -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();
});
});
@@ -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<Record<string, string>> = {
invalid_media:
"FFmpeg could not read the file as a video. Check it with `ffprobe <file>`: 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 <video> against the project folder.",
download_not_found:
"The video URL answered 404 or 410. Check the `src` of the <video>, or download the file into the project.",
};
function failureKinds(error: unknown): string[] | null {
let seen: unknown = error;
for (let depth = 0; depth < 5 && seen instanceof Error; depth++) {
const { code, failures } = seen as { code?: unknown; failures?: unknown };
if (code === "VIDEO_SOURCE_UNRENDERABLE" && Array.isArray(failures)) {
return failures.map((failure: { kind?: unknown }) => String(failure?.kind));
}
seen = seen.cause;
}
return null;
}
/** The hint for a source failure, or null when the failure is not one this can explain. */
export function sourceFailureHint(error: unknown): string | null {
const kinds = failureKinds(error);
if (!kinds || kinds.length === 0) return null;
const hints = [...new Set(kinds.map((kind) => SOURCE_HINTS[kind]))];
if (hints.some((hint) => hint === undefined)) return null;
return hints.join(" ");
}