heygen-com/hyperframes · error · Error

beginFrame probe timeout before ${label}

Error message

beginFrame probe timeout before ${label}

What it means

Thrown by awaitBeforeDeadline() when the remaining time before a shared deadline has already elapsed (remainingMs <= 0). The beginFrame capability probe uses a single 2-second budget (BEGINFRAME_PROBE_TIMEOUT_MS) across multiple sequential CDP operations (domain enable, warm-up, screenshot retries). If earlier operations consumed the entire budget, a later step discovers no time remains and throws immediately.

Source

Thrown at packages/engine/src/services/browserManager.ts:262

 */
interface BeginFrameProbeResult {
  supported: boolean;
  detail: string;
  durationMs: number;
}

const BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS = 10;
const BEGINFRAME_PROBE_TIMEOUT_MS = 2000;
const BEGINFRAME_PROBE_CLEANUP_TIMEOUT_MS = 250;

async function awaitBeforeDeadline<T>(
  operation: Promise<T>,
  deadline: number,
  label: string,
): Promise<T> {
  const remainingMs = deadline - Date.now();
  if (remainingMs <= 0) {
    throw new Error(`beginFrame probe timeout before ${label}`);
  }
  let timeout: ReturnType<typeof setTimeout> | undefined;
  try {
    return await Promise.race([
      operation,
      new Promise<never>((_, reject) => {
        timeout = setTimeout(
          () => reject(new Error(`beginFrame probe timeout during ${label}`)),
          remainingMs,
        );
      }),
    ]);
  } finally {
    if (timeout) clearTimeout(timeout);
  }
}

async function settleWithin(operation: Promise<unknown>, timeoutMs: number): Promise<boolean> {

View on GitHub (pinned to c2996c8626)

Solutions

1. Increase BEGINFRAME_PROBE_TIMEOUT_MS if the probe is timing out on slow but functional setups.
2. Ensure the Chrome process has adequate CPU/memory — containers with <1 CPU core are prone to this.
3. Pre-warm the Chrome instance before running the probe (e.g., load a simple page first).
4. If beginFrame is not supported, the probe result is 'supported: false' — verify the Chrome build includes HeadlessExperimental support.

try {
  await probeBeginFrameSupport(browser);
} catch (err) {
  if (err instanceof Error && err.message.includes('beginFrame probe timeout')) {
    // treat as unsupported; fall back to non-beginFrame capture
  }
  throw err;
}

When it happens

Trigger: awaitBeforeDeadline(operation, deadline, label) is called as part of the beginFrame probe sequence. The deadline was set to Date.now() + 2000ms at probe start. A previous CDP call (e.g., HeadlessExperimental.enable or the first screenshot attempt) took long enough that the deadline has passed by the time this step begins.

Common situations: The headless Chrome instance is slow to respond (cold start, resource-constrained container, shared CI runner). The beginFrame domain exists but is sluggish. A previous screenshot retry burned most of the budget. The probe runs during heavy system load.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• BeginFrame probe timeout before ${label}
• beginFrame screenshot returned ${bytes.length} bytes after $
• stage budget exceeded while ${label} (${budgetMs}ms)
• --executable-path requires a path
• --launch-args-json requires a path

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