stablyai/orca · error · EmulatorError

emulator_helper_failed

emulator_helper_failed

Error message

AVD "${avdName}" did not finish booting in time.

What it means

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.

Source

Thrown at src/main/emulator/android/android-avd-boot.ts:84

  avdName: string,
  known: Set<string>,
  options: AndroidBootOptions
): Promise<string> {
  let waited = 0
  while (waited < options.bootTimeoutMs) {
    const fresh = (await listRunningAdbDevices(runner, sdk)).filter(
      (device) => device.isEmulator && !known.has(device.serial)
    )
    for (const device of fresh) {
      const booted = await runner(sdk.adb, bootCompletedArgs(device.serial))
      if (isBootCompleted(booted.stdout)) {
        return device.serial
      }
    }
    await options.sleep(options.pollIntervalMs)
    waited += options.pollIntervalMs
  }
  throw new EmulatorError(
    'emulator_helper_failed',
    `AVD "${avdName}" did not finish booting in time.`
  )
}

View on GitHub (pinned to 1136503c6a)

Solutions

1. Raise bootTimeoutMs for the environment (cold boots and first-boot Play Store AVDs routinely exceed modest defaults).
2. Confirm hardware acceleration is enabled (HAXM/WHPX on Windows, HVF on macOS, KVM on Linux) — without it boot can take many minutes.
3. Watch the emulator window briefly (drop -no-window) to see where boot stalls, or check `adb logcat` once the device appears.
4. Ensure the host has enough RAM/disk for the AVD; a wedged qemu from low memory will never finish booting.
5. If the AVD image is corrupted, recreate it via avdmanager; verify the launch.error probe is not firing.

Example fix

// before: default timeout too short for cold CI boot
await bootAndroidDevice(runner, sdk, avd, {
  bootTimeoutMs: 30_000, pollIntervalMs: 1_000, sleep
})
// after: sized for cold boots + acceleration check
await bootAndroidDevice(runner, sdk, avd, {
  bootTimeoutMs: 180_000, pollIntervalMs: 2_000, sleep
})

// Pre-flight: confirm acceleration is available so boot won't crawl.
async function accelerationOk(runner, sdk): Promise<boolean> {
  // emulator -accel-check exits 0 when HAXM/HVF/KVM is present
  return (await runner(sdk.emulator, ['-accel-check'])).code === 0
}

import { EmulatorError } from '../emulator-errors'
function isBootTimeout(e: unknown): e is EmulatorError {
  return e instanceof EmulatorError && e.code === 'emulator_helper_failed'
}

try {
  return await bootAndroidDevice(runner, sdk, avd, { bootTimeoutMs: 180_000, pollIntervalMs: 2_000, sleep })
} catch (e) {
  if (e instanceof EmulatorError && e.code === 'emulator_helper_failed') {
    // cold boot can exceed short timeouts; recreate AVD if persistently wedged
    throw new Error(`Boot timed out for ${avd}; verify acceleration and AVD integrity`)
  }
  throw e
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• emulator_device_not_found
• emulator_error
• emulator_error
• emulator_error
• emulator_error

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/6bbb7c84c66fd434. Report an issue: GitHub.