Skip to content

Write HTML. Render video. Built for agents.

fix(cli): say when the Docker image build times out instead of blaming Docker (#5394)

Diego López3bf9035d2aae
diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index 904df5a818..634a2f8eeb 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -96,6 +96,10 @@ import { buildDockerRunArgs, resolveDockerPlatform } from "../utils/dockerRunArg
import { createStderrTail, DockerRenderExitError } from "../utils/dockerStderrTail.js";
import type { BrowserInstallFacts } from "../browser/installFacts.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
+import {
+ DOCKER_BUILD_TIMEOUT_MINUTES,
+ describeDockerBuildFailure,
+} from "../utils/dockerBuildFailure.js";
import { runEnvironmentChecks } from "../browser/preflight.js";
import {
detectH264EncoderModeForRender,
@@ -705,11 +709,11 @@ function ensureDockerImage(version: string, platform: string, quiet: boolean): s
tag,
tmpDir,
],
- { stdio: quiet ? "pipe" : "inherit", timeout: 600_000 },
+ { stdio: quiet ? "pipe" : "inherit", timeout: DOCKER_BUILD_TIMEOUT_MINUTES * 60_000 },
);
} catch (error: unknown) {
const message = normalizeErrorMessage(error);
- throw new Error(`Failed to build Docker image: ${message}`);
+ throw new Error(`Failed to build Docker image: ${message}`, { cause: error });
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
@@ -781,15 +785,8 @@ async function renderDocker(
try {
imageTag = ensureDockerImage(dockerVersion, platform, options.quiet);
} catch (error: unknown) {
- const message = normalizeErrorMessage(error);
- const isDockerMissing = /connect|not found|ENOENT/i.test(message);
- errorBox(
- isDockerMissing ? "Docker not available" : "Docker image build failed",
- message,
- isDockerMissing
- ? "Install Docker: https://docs.docker.com/get-docker/"
- : "Check Docker is running: docker info",
- );
+ const failure = describeDockerBuildFailure(error);
+ errorBox(failure.title, failure.message, failure.hint);
failCommand();
}
diff --git a/packages/cli/src/utils/dockerBuildFailure.test.ts b/packages/cli/src/utils/dockerBuildFailure.test.ts
new file mode 100644
index 0000000000..4084709743
--- /dev/null
+++ b/packages/cli/src/utils/dockerBuildFailure.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { describeDockerBuildFailure } from "./dockerBuildFailure.js";
+
+function spawnError(message: string, code: string): Error {
+ return Object.assign(new Error(message), { code });
+}
+
+describe("describeDockerBuildFailure", () => {
+ it("says the build timed out and that a rerun continues from the cached layers", () => {
+ const error = new Error("Failed to build Docker image: spawnSync docker ETIMEDOUT", {
+ cause: spawnError("spawnSync docker ETIMEDOUT", "ETIMEDOUT"),
+ });
+ const failure = describeDockerBuildFailure(error);
+ expect(failure.title).toBe("Docker image build timed out");
+ expect(failure.message).toContain("longer than 10 minutes");
+ expect(failure.hint).toContain("Run the same command again");
+ expect(failure.hint).not.toContain("docker info");
+ });
+
+ it("keeps pointing at the Docker install when the binary is missing", () => {
+ const error = new Error("Failed to build Docker image: spawnSync docker ENOENT", {
+ cause: spawnError("spawnSync docker ENOENT", "ENOENT"),
+ });
+ expect(describeDockerBuildFailure(error)).toEqual({
+ title: "Docker not available",
+ message: "Failed to build Docker image: spawnSync docker ENOENT",
+ hint: "Install Docker: https://docs.docker.com/get-docker/",
+ });
+ });
+
+ it("keeps the docker info hint for any other build failure", () => {
+ const error = new Error("Failed to build Docker image: Command failed: docker build", {
+ cause: spawnError("Command failed: docker build", "1"),
+ });
+ expect(describeDockerBuildFailure(error)).toEqual({
+ title: "Docker image build failed",
+ message: "Failed to build Docker image: Command failed: docker build",
+ hint: "Check Docker is running: docker info",
+ });
+ });
+});
diff --git a/packages/cli/src/utils/dockerBuildFailure.ts b/packages/cli/src/utils/dockerBuildFailure.ts
new file mode 100644
index 0000000000..b8dc5022ca
--- /dev/null
+++ b/packages/cli/src/utils/dockerBuildFailure.ts
@@ -0,0 +1,36 @@
+import { normalizeErrorMessage } from "./errorMessage.js";
+
+export const DOCKER_BUILD_TIMEOUT_MINUTES = 10;
+
+interface DockerBuildFailure {
+ title: string;
+ message: string;
+ hint: string;
+}
+
+function isSpawnTimeout(error: unknown): boolean {
+ return error instanceof Error && "code" in error && error.code === "ETIMEDOUT";
+}
+
+export function describeDockerBuildFailure(error: unknown): DockerBuildFailure {
+ if (error instanceof Error && isSpawnTimeout(error.cause)) {
+ return {
+ title: "Docker image build timed out",
+ message: `Building the render image took longer than ${DOCKER_BUILD_TIMEOUT_MINUTES} minutes, so it was stopped.`,
+ hint: "Run the same command again. Docker keeps the layers it already built, so the build picks up where it stopped.",
+ };
+ }
+ const message = normalizeErrorMessage(error);
+ if (/connect|not found|ENOENT/i.test(message)) {
+ return {
+ title: "Docker not available",
+ message,
+ hint: "Install Docker: https://docs.docker.com/get-docker/",
+ };
+ }
+ return {
+ title: "Docker image build failed",
+ message,
+ hint: "Check Docker is running: docker info",
+ };
+}