{"record":{"id":"74e2ec52fda5439f","repo":"heygen-com/hyperframes","slug":"model-download-failed-model","errorCode":null,"errorMessage":"Model download failed: ${model}","messagePattern":"Model download failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/background-removal/manager.ts","lineNumber":93,"sourceCode":"}\n\nexport function modelPath(model: ModelId = DEFAULT_MODEL): string {\n  return join(MODELS_DIR, `${model}.onnx`);\n}\n\nexport async function ensureModel(\n  model: ModelId = DEFAULT_MODEL,\n  options?: { onProgress?: (message: string) => void },\n): Promise<string> {\n  const dest = modelPath(model);\n  if (existsSync(dest)) return dest;\n\n  mkdirSync(MODELS_DIR, { recursive: true });\n  options?.onProgress?.(`Downloading ${model} weights (~168 MB)...`);\n  await downloadFile(MODEL_URLS[model], dest);\n\n  if (!existsSync(dest)) {\n    throw new Error(`Model download failed: ${model}`);\n  }\n  return dest;\n}\n","sourceCodeStart":75,"sourceCodeEnd":97,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/background-removal/manager.ts#L75-L97","documentation":"Thrown by ensureModel when, after awaiting downloadFile(MODEL_URLS[model], dest), the destination file still does not exist (existsSync false). downloadFile is expected to write the ~168 MB u2net_human_seg.onnx into ~/.cache/hyperframes/background-removal/models/; if the download silently failed (network error swallowed, disk full, permission denied, proxy blocking github.com), the file is absent. The existsSync-after-download guard converts a silent download failure into an explicit, attributable error.","triggerScenarios":"downloadFile rejected but the error was not propagated (unlikely — it is awaited), OR it resolved without writing (a stub/mock in tests). In production: a corporate proxy or firewall blocked the GitHub releases download; the cache directory is on a read-only filesystem; the disk filled mid-download; a timeout left no file behind.","commonSituations":"Corporate egress proxy blocking github.com/releases; running in a container with a read-only HOME; disk-full CI runner; a test that mocks downloadFile to resolve without writing.","solutions":["Manually download u2net_human_seg.onnx from the rembg releases and place it at ~/.cache/hyperframes/background-removal/models/u2net_human_seg.onnx.","Check network/proxy access to https://github.com/danielgatis/rembg/releases from the host.","Verify the cache directory is writable and has disk space.","Retry ensureModel after fixing the network issue; it will re-attempt the download."],"exampleFix":"// before: corporate proxy blocks github\nensureModel(); // throws: Model download failed\n\n// after\nmkdir -p ~/.cache/hyperframes/background-removal/models\ncurl -L -o ~/.cache/hyperframes/background-removal/models/u2net_human_seg.onnx \\\n  https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net_human_seg.onnx\nensureModel(); // cache hit, no download","handlingStrategy":"retry","validationCode":"import { existsSync, statSync } from 'node:fs';\nasync function ensureModelOrHint(model: ModelId): Promise<string> {\n  const dest = modelPath(model);\n  if (existsSync(dest) && statSync(dest).size > 1_000_000) return dest;\n  // pre-flight: check network/proxy before download\n  return ensureModel(model);\n}","typeGuard":null,"tryCatchPattern":"let path: string | undefined;\nfor (let attempt = 0; attempt < 3 && !path; attempt++) {\n  try { path = await ensureModel(); }\n  catch (err) {\n    if (attempt === 2) throw err;\n  }\n}","preventionTips":["Pre-download the model manually into ~/.cache/hyperframes/background-removal/models/ in air-gapped/proxied environments.","Verify network access to github.com/releases from the host.","Ensure the cache directory is writable and has sufficient disk space (~168 MB)."],"tags":["background-removal","model","download","network","cache"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}