{"record":{"id":"8925c55f863837d4","repo":"stablyai/orca","slug":"emulator-device-not-found","errorCode":"emulator_device_not_found","errorMessage":"\"${deviceOrName}\" is not a running device or a known AVD.","messagePattern":"\"(.+?)\" is not a running device or a known AVD\\.","errorType":"exception","errorClass":"EmulatorError","httpStatus":null,"severity":"error","filePath":"src/main/emulator/android/android-avd-boot.ts","lineNumber":36,"sourceCode":"export async function bootAndroidDevice(\n  runner: AndroidCommandRunner,\n  sdk: AndroidSdkPaths,\n  deviceOrName: string,\n  options: AndroidBootOptions\n): Promise<string> {\n  const running = await listRunningAdbDevices(runner, sdk)\n  if (running.some((device) => device.serial === deviceOrName)) {\n    return deviceOrName\n  }\n  const existing = await findRunningAvdSerial(runner, sdk, deviceOrName, running)\n  if (existing) {\n    return existing\n  }\n  // Validate the target is a real AVD before spawning, so a stale/offline serial\n  // doesn't launch an invalid `-avd` and burn the full boot timeout.\n  const avds = parseAvdList((await runner(sdk.emulator, listAvdsArgs)).stdout)\n  if (!avds.includes(deviceOrName)) {\n    throw new EmulatorError(\n      'emulator_device_not_found',\n      `\"${deviceOrName}\" is not a running device or a known AVD.`\n    )\n  }\n  const known = new Set(running.map((device) => device.serial))\n  launchAvd(sdk.emulator, deviceOrName)\n  return waitForNewBootedSerial(runner, sdk, deviceOrName, known, options)\n}\n\n// Launches the emulator with spawn (NOT the command runner: execFile would kill\n// the long-running, verbose emulator at its timeout / stdout maxBuffer). It is\n// NOT detached: DETACHED_PROCESS gives the console-subsystem emulator no console,\n// so it (and its qemu/netsim children) pop their own visible one. windowsHide\n// gives it a hidden console instead; unref lets the app exit without waiting, and\n// managed emulators are shut down on quit anyway. -no-window keeps it headless.\nfunction launchAvd(emulatorPath: string, avdName: string): void {\n  const child = spawn(emulatorPath, [...bootAvdArgs(avdName), '-no-window'], {\n    stdio: 'ignore',","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/emulator/android/android-avd-boot.ts#L18-L54","documentation":"Thrown by bootAndroidDevice when the requested deviceOrName is neither a currently running adb serial nor an entry in `emulator -list-avds`. The check exists specifically so a stale/offline serial cannot launch an invalid `-avd` invocation and waste the entire boot timeout. It is an early-fail guard executed before any emulator process is spawned.","triggerScenarios":"bootAndroidDevice(runner, sdk, deviceOrName, options) where deviceOrName is not in listRunningAdbDevices serials, not resolvable via findRunningAvdSerial, AND not present in parseAvdList of the emulator's AVD list. Common form: typo'd AVD name, a serial that belonged to a now-disconnected device, or an AVD that was deleted via avdmanager.","commonSituations":"User passes a device nickname or partial name that doesn't match the AVD's registered name; the AVD was created under a different ANDROID_AVD_HOME; emulator binary missing so list-avds returns empty; CI cache wiped ~/.android/avd; referencing an emulator-5554 serial after the emulator was killed.","solutions":["List valid targets first: run `emulator -list-avds` and `adb devices`, then pass an exact AVD name or running serial.","If you intended a serial, boot the corresponding AVD first or ensure the emulator process is running.","Verify ANDROID_HOME/ANDROID_AVD_HOME point at the directory holding the AVD ini files.","Recreate the AVD with avdmanager if it was deleted."],"exampleFix":"// before: passing a guessed name\nawait bootAndroidDevice(runner, sdk, 'Pixel7', opts) // not a real AVD\n// after: discover then boot\nconst avds = parseAvdList((await runner(sdk.emulator, listAvdsArgs)).stdout)\nconst name = avds.find(a => a.startsWith('Pixel'))\nif (!name) throw new Error(`no matching AVD; available: ${avds.join(', ')}`)\nawait bootAndroidDevice(runner, sdk, name, opts)","handlingStrategy":"validation","validationCode":"// Confirm the target exists as an AVD before invoking boot.\nimport { listAvdsArgs, parseAvdList } from './avd-manager'\nimport { listRunningAdbDevices } from './android-device-inventory'\nasync function resolveBootTarget(runner, sdk, name: string): Promise<string | null> {\n  const running = await listRunningAdbDevices(runner, sdk)\n  if (running.some(d => d.serial === name)) return name\n  const avds = parseAvdList((await runner(sdk.emulator, listAvdsArgs)).stdout)\n  return avds.includes(name) ? name : null\n}","typeGuard":"import { EmulatorError } from '../emulator-errors'\nfunction isDeviceNotFound(e: unknown): e is EmulatorError {\n  return e instanceof EmulatorError && e.code === 'emulator_device_not_found'\n}","tryCatchPattern":"try {\n  await bootAndroidDevice(runner, sdk, target, opts)\n} catch (e) {\n  if (e instanceof EmulatorError && e.code === 'emulator_device_not_found') {\n    const avds = parseAvdList((await runner(sdk.emulator, listAvdsArgs)).stdout)\n    throw new Error(`Unknown target '${target}'. Available AVDs: ${avds.join(', ')}`)\n  }\n  throw e\n}","preventionTips":["Always source device/AVD names from `emulator -list-avds`, never hand-typed.","Verify ANDROID_HOME/ANDROID_AVD_HOME point at the AVD directory.","Re-list AVDs after creating or deleting with avdmanager."],"tags":["android","avd","device-not-found","emulator"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}