{"record":{"id":"bc943fff3950ecda","repo":"heygen-com/hyperframes","slug":"background-preview-did-not-become-ready-see-log","errorCode":null,"errorMessage":"background preview did not become ready; see ${logPath}","messagePattern":"background preview did not become ready; see (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/previewLifecycle.ts","lineNumber":250,"sourceCode":"      existing,\n      dependencies.forceNew === true,\n      dependencies.browserGpuMode,\n    );\n    if (server) {\n      const session = {\n        pid,\n        port: server.port,\n        projectDir: resolve(projectDir),\n        logPath,\n      };\n      writePreviewSession(session, stateHome);\n      return { type: \"started\", ...session };\n    }\n    await sleep(200);\n  }\n\n  (dependencies.kill ?? stopProcess)(pid);\n  throw new Error(`background preview did not become ready; see ${logPath}`);\n}\n\nexport async function stopBackgroundPreview(\n  projectDir: string,\n  startPort: number,\n  dependencies: LifecycleDependencies = {},\n): Promise<boolean> {\n  const scan = dependencies.scan ?? scanActiveServers;\n  const stateHome = dependencies.stateHome ?? defaultStateHome();\n  const saved = readPreviewSession(projectDir, stateHome);\n  const scanStart = saved?.port ?? startPort;\n  const server = matchingServer(await scan(scanStart), projectDir);\n  // A saved PID can be reused after a crashed preview, so only trust it while\n  // a currently reachable server proves this exact project is still running.\n  const pid = Number(server ? (server.pid ?? saved?.pid) : undefined);\n  if (!Number.isInteger(pid) || pid <= 0) {\n    removePreviewSession(projectDir, stateHome);\n    return false;","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/previewLifecycle.ts#L232-L268","documentation":"Thrown when the detached background preview server fails to become ready within the polling window. The lifecycle code writes a session file once a matching server answers the readiness scan; if that never happens it kills the spawned pid and throws, pointing at the log file the child's stdio was routed to for diagnosis.","triggerScenarios":"startBackgroundPreview spawns the child, then loops polling scanActiveServers until the server appears (200ms sleep between attempts). If the attempt budget is exhausted the pid is stopped and this error is raised at previewLifecycle.ts:250.","commonSituations":"The preview server crashed during startup (port in use, missing project files, a composition syntax error) so it never answers; the chosen start port is firewalled; heavy load made startup exceed the retry budget; a stale lock or bound port from a previous run.","solutions":["Read the referenced logPath file — the child's stdout/stderr were redirected there","Ensure the start port is free: stop other preview servers (`hyperframes preview --stop`) or pick another port","Run the preview in the foreground (`hyperframes preview`) to see startup errors directly","Check the composition lints: `npx hyperframes lint`"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await startBackgroundPreview(projectDir, port, {...});\n} catch (e) {\n  if (e.message.includes(\"did not become ready\")) {\n    const log = readFileSync(e.message.match(/see (.*)$/)?.[1] ?? \"\", \"utf8\");\n    console.error(log); // surface the child's startup error\n  }\n  throw e;\n}","preventionTips":["Run preview in the foreground first to confirm it starts cleanly","Keep the start port free of other listeners","Lint the composition before relying on the background server","Inspect the referenced logPath on every failure"],"tags":["preview","process-management","startup","network"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}