{"record":{"id":"6bbb7c84c66fd434","repo":"stablyai/orca","slug":"emulator-helper-failed","errorCode":"emulator_helper_failed","errorMessage":"AVD \"${avdName}\" did not finish booting in time.","messagePattern":"AVD \"(.+?)\" did not finish booting in time\\.","errorType":"exception","errorClass":"EmulatorError","httpStatus":null,"severity":"error","filePath":"src/main/emulator/android/android-avd-boot.ts","lineNumber":84,"sourceCode":"  avdName: string,\n  known: Set<string>,\n  options: AndroidBootOptions\n): Promise<string> {\n  let waited = 0\n  while (waited < options.bootTimeoutMs) {\n    const fresh = (await listRunningAdbDevices(runner, sdk)).filter(\n      (device) => device.isEmulator && !known.has(device.serial)\n    )\n    for (const device of fresh) {\n      const booted = await runner(sdk.adb, bootCompletedArgs(device.serial))\n      if (isBootCompleted(booted.stdout)) {\n        return device.serial\n      }\n    }\n    await options.sleep(options.pollIntervalMs)\n    waited += options.pollIntervalMs\n  }\n  throw new EmulatorError(\n    'emulator_helper_failed',\n    `AVD \"${avdName}\" did not finish booting in time.`\n  )\n}\n","sourceCodeStart":66,"sourceCodeEnd":89,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/emulator/android/android-avd-boot.ts#L66-L89","documentation":"Thrown by waitForNewBootedSerial after the AVD was launched (spawn, -no-window) but `sys.boot_completed` never reported completion within options.bootTimeoutMs. It means the emulator process started yet the Android system did not finish booting in the allotted window. This is an emulator-helper timeout, not an adb error.","triggerScenarios":"launchAvd spawned the emulator successfully, the poll loop in waitForNewBootedSerial ran for bootTimeoutMs / pollIntervalMs iterations checking isBootCompleted(adb shell getprop sys.boot_completed), and no fresh emulator serial returned a completed boot. The fresh-device filter requires isEmulator && !known.has(serial), so a serial that never appeared in adb devices also lands here.","commonSituations":"Cold boot on an underpowered CI runner exceeding the timeout; a corrupted AVD image that hangs early in boot; insufficient host RAM/disk causing extremely slow boot; HAXM/HVF/KVM acceleration disabled so the emulator runs at a crawl; a first-boot Google Play AVD that downloads/optimizes; emulator process crashed silently after spawn (the launch.error probe fires but the loop still waits).","solutions":["Raise bootTimeoutMs for the environment (cold boots and first-boot Play Store AVDs routinely exceed modest defaults).","Confirm hardware acceleration is enabled (HAXM/WHPX on Windows, HVF on macOS, KVM on Linux) — without it boot can take many minutes.","Watch the emulator window briefly (drop -no-window) to see where boot stalls, or check `adb logcat` once the device appears.","Ensure the host has enough RAM/disk for the AVD; a wedged qemu from low memory will never finish booting.","If the AVD image is corrupted, recreate it via avdmanager; verify the launch.error probe is not firing."],"exampleFix":"// before: default timeout too short for cold CI boot\nawait bootAndroidDevice(runner, sdk, avd, {\n  bootTimeoutMs: 30_000, pollIntervalMs: 1_000, sleep\n})\n// after: sized for cold boots + acceleration check\nawait bootAndroidDevice(runner, sdk, avd, {\n  bootTimeoutMs: 180_000, pollIntervalMs: 2_000, sleep\n})","handlingStrategy":"retry","validationCode":"// Pre-flight: confirm acceleration is available so boot won't crawl.\nasync function accelerationOk(runner, sdk): Promise<boolean> {\n  // emulator -accel-check exits 0 when HAXM/HVF/KVM is present\n  return (await runner(sdk.emulator, ['-accel-check'])).code === 0\n}","typeGuard":"import { EmulatorError } from '../emulator-errors'\nfunction isBootTimeout(e: unknown): e is EmulatorError {\n  return e instanceof EmulatorError && e.code === 'emulator_helper_failed'\n}","tryCatchPattern":"try {\n  return await bootAndroidDevice(runner, sdk, avd, { bootTimeoutMs: 180_000, pollIntervalMs: 2_000, sleep })\n} catch (e) {\n  if (e instanceof EmulatorError && e.code === 'emulator_helper_failed') {\n    // cold boot can exceed short timeouts; recreate AVD if persistently wedged\n    throw new Error(`Boot timed out for ${avd}; verify acceleration and AVD integrity`)\n  }\n  throw e\n}","preventionTips":["Size bootTimeoutMs to the slowest boot path (cold boot, first-boot Play Store AVDs).","Verify hardware acceleration (HAXM/HVF/KVM) is enabled before relying on boot.","Drop -no-window temporarily to observe where a stalled boot hangs."],"tags":["android","avd","boot-timeout","emulator","ci"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}