{"record":{"id":"6cc1b5f5a39f4144","repo":"heygen-com/hyperframes","slug":"beginframe-screenshot-returned-bytes-length-byt","errorCode":null,"errorMessage":"beginFrame screenshot returned ${bytes.length} bytes after ${BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS} attempts with signature ${bytes.length >= 4 ? bytes.subarray(0, 4).toString(\"hex\") : \"<empty>\"}","messagePattern":"beginFrame screenshot returned (.+?) bytes after (.+?) attempts with signature (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/services/browserManager.ts","lineNumber":388,"sourceCode":"        `screenshot beginFrame attempt ${attempts}`,\n      );\n      const screenshot = response.screenshotData ?? \"\";\n      bytes = screenshot ? Buffer.from(screenshot, \"base64\") : Buffer.alloc(0);\n      isPng =\n        bytes.length >= 8 &&\n        bytes[0] === 0x89 &&\n        bytes[1] === 0x50 &&\n        bytes[2] === 0x4e &&\n        bytes[3] === 0x47;\n      if (isPng) break;\n      await awaitBeforeDeadline(\n        new Promise((resolveDelay) => setTimeout(resolveDelay, 10)),\n        deadline,\n        `screenshot retry delay ${attempts}`,\n      );\n    }\n    if (!isPng) {\n      throw new Error(\n        `beginFrame screenshot returned ${bytes.length} bytes after ` +\n          `${BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS} attempts with signature ` +\n          `${bytes.length >= 4 ? bytes.subarray(0, 4).toString(\"hex\") : \"<empty>\"}`,\n      );\n    }\n    await awaitBeforeDeadline(client.detach(), deadline, \"CDP detach\").catch(() => {});\n    result = {\n      supported: true,\n      detail:\n        `enable + warm-up + ${bytes.length}-byte PNG beginFrame succeeded ` +\n        `after ${attempts} screenshot attempt(s)`,\n      durationMs: Date.now() - started,\n    };\n  } catch (error) {\n    result = {\n      supported: false,\n      detail: error instanceof Error ? error.message : String(error),\n      durationMs: Date.now() - started,","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/services/browserManager.ts#L370-L406","documentation":"Thrown after the beginFrame screenshot probe exhausts all BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS (10) retries without obtaining a valid PNG. Each attempt calls screenshot and checks the first 4 bytes for the PNG magic number (89 50 4E 47). The error includes byte count and hex signature for diagnostics, revealing whether Chrome returned empty data, JPEG, or garbage.","triggerScenarios":"The probe loop calls client.send('Page.captureScreenshot', { format: 'png' }) up to 10 times with 10ms delays. Every result fails the PNG signature check (bytes[0]===0x89 && bytes[1]===0x50 && bytes[2]===0x4e && bytes[3]===0x47). After the last attempt, the isPng flag is still false and the error fires.","commonSituations":"The Chrome headless shell doesn't support beginFrame screenshot capture properly (older or stripped build). The page hasn't rendered any content yet (empty/blank screenshots). A GPU/compositing issue produces corrupted frame data. The headless shell is a non-standard build that returns JPEG or raw data instead of PNG.","solutions":["Check the hex signature in the error: '<empty>' means no data at all (beginFrame not functional); a JPEG signature means format negotiation failed.","Use a standard Chrome headless shell build: run hyperframes browser ensure.","If on a custom Chrome, verify it supports HeadlessExperimental.beginFrame with PNG screenshots.","The probe gracefully reports supported: false on failure — ensure downstream code falls back to non-beginFrame capture."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"let beginFrameSupported = true;\ntry {\n  const result = await probeBeginFrameSupport(browser);\n  beginFrameSupported = result.supported;\n} catch (err) {\n  if (err instanceof Error && err.message.includes('beginFrame screenshot returned')) {\n    beginFrameSupported = false;\n  } else {\n    throw err;\n  }\n}\n// use beginFrame capture only if beginFrameSupported === true","preventionTips":["Use hyperframes browser ensure to get a standard Chrome headless shell that supports beginFrame PNG screenshots.","Inspect the hex signature in the error message to diagnose the specific Chrome output format issue.","Treat probe failure as 'unsupported' and implement a non-beginFrame fallback capture path."],"tags":["browser","beginframe","screenshot","png","probe","diagnostics"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}