{"record":{"id":"6898bf2ec08730ba","repo":"heygen-com/hyperframes","slug":"whisper-unavailable","errorCode":"WHISPER_UNAVAILABLE","errorMessage":"whisper-cpp not found. Install: ${getInstallInstructions()}","messagePattern":"whisper-cpp not found\\. Install: (.+?)","errorType":"exception","errorClass":"WhisperUnavailableError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/whisper/manager.ts","lineNumber":210,"sourceCode":"      });\n      const installed = findFromSystem();\n      if (installed) return { ...installed, source: \"brew\" };\n    } catch {\n      // brew failed — fall through\n    }\n  }\n\n  // 3. Build from source (needs git + cmake + C compiler)\n  if (hasGit() && hasCmake()) {\n    try {\n      return buildFromSource(options?.onProgress);\n    } catch {\n      // build failed — fall through\n    }\n  }\n\n  // 4. Give up — tell the user how\n  throw new WhisperUnavailableError(`whisper-cpp not found. Install: ${getInstallInstructions()}`);\n}\n\nexport async function ensureModel(\n  model: string = DEFAULT_MODEL,\n  options?: { onProgress?: (message: string) => void },\n): Promise<string> {\n  const modelPath = join(MODELS_DIR, `ggml-${model}.bin`);\n  if (existsSync(modelPath)) return modelPath;\n\n  mkdirSync(MODELS_DIR, { recursive: true });\n\n  options?.onProgress?.(`Downloading model ${model}...`);\n  await downloadFile(getModelUrl(model), modelPath);\n\n  if (!existsSync(modelPath)) {\n    throw new Error(`Model download failed: ${model}`);\n  }\n","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/whisper/manager.ts#L192-L228","documentation":"Thrown as WhisperUnavailableError (with code 'WHISPER_UNAVAILABLE') when all four whisper-cpp resolution strategies have been exhausted: no existing binary found (env, system, brew, build), Homebrew install failed or is unavailable, and source build failed or prerequisites are missing. The error includes platform-specific install instructions. Callers that treat captions as optional can detect this via the exported isWhisperUnavailable type guard and skip gracefully.","triggerScenarios":"Calling ensureWhisper on a system with no whisper-cpp installed, no Homebrew, and no cmake/C compiler toolchain; all resolution paths (findFromEnv, findFromSystem, findFromSystem via brew, buildFromSource) returned null or threw.","commonSituations":"First-time use on a minimal Linux server or CI container without build tools; Windows without a pre-built binary or compiler; a system where whisper-cpp was previously installed but has since been removed.","solutions":["Follow the platform-specific instructions in the error message (brew install whisper-cpp on macOS, or install cmake + build-essential and retry).","Install whisper-cpp manually and set HYPERFRAMES_WHISPER to the binary path.","If using the Parakeet engine instead, ensure parakeet-mlx is installed and pass --engine parakeet.","If captions are optional for your workflow, catch WhisperUnavailableError via isWhisperUnavailable and skip transcription."],"exampleFix":"// Catch and skip when captions are optional\nimport { isWhisperUnavailable } from \"@hyperframes/cli/whisper/manager\";\ntry {\n  await ensureWhisper();\n} catch (err) {\n  if (isWhisperUnavailable(err)) {\n    console.warn(\"whisper-cpp unavailable — skipping captions\");\n    return;\n  }\n  throw err;\n}","handlingStrategy":"fallback","validationCode":"import { findWhisper } from \"./manager.js\";\n\nconst existing = findWhisper();\nif (!existing) {\n  console.warn(\"whisper-cpp not installed. Captions will be skipped.\");\n}","typeGuard":"import { isWhisperUnavailable } from \"./manager.js\";\n\n// isWhisperUnavailable is the exported guard — use it to detect this error\nfunction isOptionalCaptions(err: unknown): boolean {\n  return isWhisperUnavailable(err);\n}","tryCatchPattern":"import { isWhisperUnavailable } from \"./manager.js\";\n\ntry {\n  await ensureWhisper({ onProgress: console.log });\n} catch (err) {\n  if (isWhisperUnavailable(err)) {\n    // Captions are optional for this workflow — skip gracefully\n    console.warn(\"whisper-cpp unavailable — skipping transcription.\");\n    return null;\n  }\n  throw err;\n}","preventionTips":["Always use isWhisperUnavailable to detect this specific error and handle it as an environment condition, not a crash.","For optional-caption workflows, check findWhisper() before calling ensureWhisper to fail faster.","Install whisper-cpp via Homebrew or set HYPERFRAMES_WHISPER to avoid this in CI/production."],"tags":["whisper","dependencies","environment","captions"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}