whisper-cpp build failed. Ensure cmake and a C compiler are

Error message

whisper-cpp build failed. Ensure cmake and a C compiler are installed.${detail}

What it means

Thrown when building whisper.cpp from source fails — the execFileSync call for the cmake/make build process threw an error. The catch block extracts the last 500 characters of stderr for the detail, deletes the build directory so the next attempt starts fresh, and throws with guidance to install cmake and a C compiler. This is one of the resolution strategies in findWhisper/ensureWhisper before giving up entirely.

Source

Thrown at packages/cli/src/whisper/manager.ts:137

    execFileSync("cmake", ["-B", "build"], {
      cwd: BUILD_DIR,
      stdio: ["pipe", "pipe", "pipe"],
      timeout: 120_000,
    });
    execFileSync("cmake", ["--build", "build", "--config", "Release", "-j"], {
      cwd: BUILD_DIR,
      stdio: ["pipe", "pipe", "pipe"],
      timeout: 300_000,
    });
  } catch (err: unknown) {
    // Build failed — capture diagnostics, then clean up so next attempt starts fresh
    let detail = "";
    if (err && typeof err === "object" && "stderr" in err) {
      const stderr = String(err.stderr).trim();
      if (stderr) detail = `\n${stderr.slice(-500)}`;
    }
    rmSync(BUILD_DIR, { recursive: true, force: true });
    throw new Error(
      `whisper-cpp build failed. Ensure cmake and a C compiler are installed.${detail}`,
    );
  }

  const result = findBuiltBinary();
  if (!result) throw new Error("Build completed but whisper-cli not found");
  return result;
}

// --- Public API -------------------------------------------------------------

export function findWhisper(): WhisperResult | undefined {
  return findFromEnv() ?? findFromSystem() ?? findBuiltBinary();
}

export function getInstallInstructions(): string {
  if (platform() === "darwin") {
    return "brew install whisper-cpp";

View on GitHub (pinned to c2996c8626)

Solutions

Install cmake and a C compiler: on macOS run xcode-select --install; on Debian/Ubuntu run apt install cmake build-essential; on Fedora run dnf install cmake gcc-c++.
Check the stderr detail in the error message for the specific build failure.
On macOS, use Homebrew instead: brew install whisper-cpp (skips source build entirely).
Alternatively, install whisper-cpp manually and ensure it's on PATH or set the HYPERFRAMES_WHISPER env var.

Defensive patterns

Strategy: fallback

Validate before calling

import { execFileSync } from "node:child_process";

function hasBuildPrerequisites(): { cmake: boolean; compiler: boolean } {
  const cmake = (() => { try { execFileSync("cmake", ["--version"], { stdio: "ignore" }); return true; } catch { return false; } })();
  const cc = (() => { try { execFileSync("cc", ["--version"], { stdio: "ignore" }); return true; } catch { return false; } })();
  return { cmake, compiler: cc };
}

Try / catch

import { isWhisperUnavailable } from "./manager.js";

try {
  await ensureWhisper();
} catch (err) {
  if (isWhisperUnavailable(err)) {
    // Build failed as part of the resolution chain — already fell through.
    // Skip captions or guide the user.
  }
  // For build-specific errors, check stderr detail in err.message
  if (err.message.includes("build failed")) {
    console.error(`Install cmake and a C compiler, then retry.`);
  }
}

Prevention

Install cmake and a C compiler before first use (build-essential on Linux, Xcode CLT on macOS).
On macOS, prefer Homebrew (brew install whisper-cpp) to skip source builds entirely.
Set HYPERFRAMES_WHISPER to a pre-built binary to avoid building from source.

When it happens

Trigger: cmake or a C compiler (gcc/clang) is not installed or not on PATH; the cmake configure step fails (missing dependencies, wrong cmake version); the compilation step fails (out of memory, compiler error); the build times out after 300 seconds.

Common situations: Minimal CI containers without build-essential or cmake; macOS without Xcode Command Line Tools; a system with an incompatible compiler version; disk full during the build.

Related errors

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