What causes "Failed to build Docker image: ${message}" in heygen-com/hyperframes?

Read the normalized message — it usually contains docker's own error line

heygen-com/hyperframes · error · Error

Failed to build Docker image: ${message}

Error message

Failed to build Docker image: ${message}

What it means

Thrown when the `docker build` invocation inside renderDocker exits non-zero. The underlying error is normalized into a message and wrapped so the caller sees a single actionable failure rather than a raw Node ENOENT/exit-code object. The temp build context is cleaned up in the finally block regardless of outcome.

Source

Thrown at packages/cli/src/commands/render.ts:607

    execFileSync(
      "docker",
      [
        "build",
        "--platform",
        platform,
        "--build-arg",
        `HYPERFRAMES_VERSION=${version}`,
        "--build-arg",
        `TARGETARCH=${targetArch}`,
        "-t",
        tag,
        tmpDir,
      ],
      { stdio: quiet ? "pipe" : "inherit", timeout: 600_000 },
    );
  } catch (error: unknown) {
    const message = normalizeErrorMessage(error);
    throw new Error(`Failed to build Docker image: ${message}`);
  } finally {
    rmSync(tmpDir, { recursive: true, force: true });
  }

  if (!quiet) console.log(c.dim(`  Docker image: ${tag} (built)`));
  return tag;
}

/**
 * Resolves the Docker `--platform` for this host and enforces the constraints
 * that come with it — keeping that policy out of `renderDocker` so the
 * orchestrator stays focused on build/run wiring. May terminate the process
 * via errorBox on unrecoverable mismatches (e.g. --gpu on arm64).
 */
function resolveDockerHostPlatform(options: RenderOptions): string {
  const platform = resolveDockerPlatform();

  // Docker Desktop on Apple Silicon (and colima with VZ) doesn't implement

View on GitHub (pinned to c2996c8626)

Solutions

Read the normalized message — it usually contains docker's own error line
Ensure the Docker daemon is up: `docker info`
Re-run with quiet off to get inherited build output for full logs
Free disk space / prune Docker: `docker system prune`
Pre-pull the base image if your network is rate-limited

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFileSync } from "node:child_process";
function dockerDaemonUp(): boolean {
  try { execFileSync("docker", ["info"], { stdio: "ignore", timeout: 5000 }); return true; }
  catch { return false; }
}

Try / catch

try {
  await renderDocker({ ... });
} catch (e) {
  if (e.message.startsWith("Failed to build Docker image:")) {
    // inspect message, pre-pull base image, free disk, then retry non-quiet
  }
  throw e;
}

Prevention

Pre-flight with `docker info` before invoking docker render
Run with quiet off the first time to capture full build logs
Pre-pull base images on rate-limited networks
Keep Docker disk headroom (prune periodically)

When it happens

Trigger: renderDocker runs `docker build` with version/arch build-args and a 600s timeout (stdio piped when quiet, inherited otherwise); any non-zero exit or timeout is caught at render.ts:607 and re-thrown.

Common situations: Docker daemon not running; disk full; a Dockerfile.render step fails (missing base image, network blocked from pulling images); build exceeded the 10-minute timeout; incorrect TARGETARCH build-arg; rate-limited registry.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/aba90227e262b0a1. Report an issue: GitHub.