heygen-com/hyperframes · error

Model download failed: ${model}

Error message

Model download failed: ${model}

What it means

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.

Source

Thrown at packages/cli/src/background-removal/manager.ts:93

}

export function modelPath(model: ModelId = DEFAULT_MODEL): string {
  return join(MODELS_DIR, `${model}.onnx`);
}

export async function ensureModel(
  model: ModelId = DEFAULT_MODEL,
  options?: { onProgress?: (message: string) => void },
): Promise<string> {
  const dest = modelPath(model);
  if (existsSync(dest)) return dest;

  mkdirSync(MODELS_DIR, { recursive: true });
  options?.onProgress?.(`Downloading ${model} weights (~168 MB)...`);
  await downloadFile(MODEL_URLS[model], dest);

  if (!existsSync(dest)) {
    throw new Error(`Model download failed: ${model}`);
  }
  return dest;
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Manually download u2net_human_seg.onnx from the rembg releases and place it at ~/.cache/hyperframes/background-removal/models/u2net_human_seg.onnx.
2. Check network/proxy access to https://github.com/danielgatis/rembg/releases from the host.
3. Verify the cache directory is writable and has disk space.
4. Retry ensureModel after fixing the network issue; it will re-attempt the download.

Example fix

// before: corporate proxy blocks github
ensureModel(); // throws: Model download failed

// after
mkdir -p ~/.cache/hyperframes/background-removal/models
curl -L -o ~/.cache/hyperframes/background-removal/models/u2net_human_seg.onnx \
  https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net_human_seg.onnx
ensureModel(); // cache hit, no download

import { existsSync, statSync } from 'node:fs';
async function ensureModelOrHint(model: ModelId): Promise<string> {
  const dest = modelPath(model);
  if (existsSync(dest) && statSync(dest).size > 1_000_000) return dest;
  // pre-flight: check network/proxy before download
  return ensureModel(model);
}

let path: string | undefined;
for (let attempt = 0; attempt < 3 && !path; attempt++) {
  try { path = await ensureModel(); }
  catch (err) {
    if (attempt === 2) throw err;
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Model download failed: ${model}
• ONNX session is missing input or output bindings
• Model did not return output '${outputName}'
• Cached Chrome binary was missing at ${fromCache.staleHyperfr
• Failed to download ${url}: HTTP ${res.status} ${res.statusTe

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