What causes "freeze failed: ${size} bytes exceeds ${MAX_FREEZE_BYTES} cap" in heygen-com/hyperframes?

Compress or downscale the source file below 256 MiB before importing.

heygen-com/hyperframes · error · Error

freeze failed: ${size} bytes exceeds ${MAX_FREEZE_BYTES} cap

Error message

freeze failed: ${size} bytes exceeds ${MAX_FREEZE_BYTES} cap

What it means

Thrown by freezeLocalFile when statSync(srcPath).size exceeds MAX_FREEZE_BYTES (256 MiB). freezeLocalFile copies a file already on disk into the freeze destination; the size check guards the same disk-fill risk as freezeBytes/freezeUrl but reads the actual filesystem size via statSync rather than a buffer length or HTTP header. The copy (copyFileSync) never runs if the cap is exceeded.

Source

Thrown at packages/core/src/figma/freeze.ts:64

  const host = parsed.hostname;
  return host === "figma.com" || host.endsWith(".figma.com") || host.endsWith(".amazonaws.com");
}

export async function freezeUrl(url: string, destPath: string): Promise<number> {
  if (!isAllowedFreezeUrl(url))
    throw new Error(`freeze failed: refusing non-figma url ${url} (https + figma hosts only)`);
  const res = await fetch(url);
  if (!res.ok) throw new Error(`freeze failed: HTTP ${res.status}`);
  const declared = Number(res.headers.get("content-length") ?? 0);
  if (exceedsFreezeCap(declared))
    throw new Error(`freeze failed: content-length ${declared} exceeds ${MAX_FREEZE_BYTES} cap`);
  return freezeBytes(new Uint8Array(await res.arrayBuffer()), destPath);
}

export function freezeLocalFile(srcPath: string, destPath: string): void {
  const size = statSync(srcPath).size;
  if (exceedsFreezeCap(size))
    throw new Error(`freeze failed: ${size} bytes exceeds ${MAX_FREEZE_BYTES} cap`);
  mkdirSync(dirname(destPath), { recursive: true });
  copyFileSync(srcPath, destPath);
}

View on GitHub (pinned to c2996c8626)

Solutions

Compress or downscale the source file below 256 MiB before importing.
Verify srcPath points at the intended exported asset, not a raw/source file.
For video, transcode to a lower bitrate or resolution.
If a genuine large asset is required and you accept the disk cost, raise MAX_FREEZE_BYTES in a fork.

Defensive patterns

Strategy: validation

Validate before calling

import { statSync } from 'node:fs';
import { exceedsFreezeCap } from '.../figma/freeze';
export function assertLocalUnderCap(srcPath: string): void {
  const size = statSync(srcPath).size;
  if (exceedsFreezeCap(size)) {
    throw new Error(`${srcPath} is ${size} bytes — compress below the 256 MiB cap first`);
  }
}
assertLocalUnderCap(srcPath);
freezeLocalFile(srcPath, dest);

Try / catch

try {
  freezeLocalFile(srcPath, dest);
} catch (err) {
  if (err instanceof Error && /exceeds .* cap/.test(err.message)) {
    // prompt user to compress/transcode the source file
  } else throw err;
}

Prevention

Compress or transcode large local assets below the cap before importing.
Verify srcPath points at the intended asset, not a raw source file.
Run statSync-based pre-checks so the error message names the file path.

When it happens

Trigger: Calling freezeLocalFile on a >256 MiB local image/video; pointing srcPath at a huge source file by mistake (e.g. a raw design file rather than the exported asset); a downloaded asset that was placed on disk by another step and exceeds the cap.

Common situations: User drops a large pre-rendered video into the project and the import flow calls freezeLocalFile on it; srcPath resolves to the wrong file (typo) hitting a huge file; a screen-recording asset that's too large.

Related errors

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