{"record":{"id":"e6dc00a78200f099","repo":"stablyai/orca","slug":"emulator-not-macos","errorCode":"emulator_not_macos","errorMessage":"iOS Simulator requires macOS with Xcode Command Line Tools.","messagePattern":"iOS Simulator requires macOS with Xcode Command Line Tools\\.","errorType":"exception","errorClass":"EmulatorError","httpStatus":null,"severity":"error","filePath":"src/main/emulator/simctl-simulator-devices.ts","lineNumber":126,"sourceCode":"\n  try {\n    const raw = await execServeSimCommand(serveSimExecutable, ['--list', '-q'], {\n      json: true,\n      timeoutMs: 10_000\n    })\n    if (raw && typeof raw === 'object') {\n      const device = (raw as { device?: unknown }).device\n      if (typeof device === 'string' && device.toLowerCase().includes(deviceOrName.toLowerCase())) {\n        return device\n      }\n    }\n  } catch {}\n  return deviceOrName\n}\n\nexport async function ensureSimulatorBooted(udid: string): Promise<void> {\n  if (platform() !== 'darwin') {\n    throw new EmulatorError(\n      'emulator_not_macos',\n      'iOS Simulator requires macOS with Xcode Command Line Tools.'\n    )\n  }\n  const devices = await listSimulatorDevices()\n  const device = devices.find((candidate) => candidate.udid === udid)\n  if (!device) {\n    throw new EmulatorError(\n      'emulator_device_not_found',\n      `Simulator ${udid} not found. Create one via Xcode > Window > Devices and Simulators.`\n    )\n  }\n  if (device.state === 'Booted') {\n    return\n  }\n\n  try {\n    await new Promise<void>((resolve, reject) => {","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/emulator/simctl-simulator-devices.ts#L108-L144","documentation":"ensureSimulatorBooted guards on platform() === 'darwin' and refuses on Linux/Windows because the iOS Simulator depends on CoreSimulator plus Xcode Command Line Tools. The check runs before any simctl invocation.","triggerScenarios":"ensureSimulatorBooted(udid) is called when platform() !== 'darwin' (simctl-simulator-devices.ts:125-129).","commonSituations":"Running the iOS emulator backend on Linux/Windows; CI on non-mac runners; platform() reporting unexpectedly due to a containerized/WSL environment.","solutions":["Run on macOS with Xcode + Command Line Tools installed.","Use the Android backend on Linux/Windows hosts.","Gate iOS emulator features behind a macOS host check in your own code."],"exampleFix":"// before\nawait ensureSimulatorBooted(udid) // on Linux -> emulator_not_macos\n\n// after\nimport { platform } from 'node:os'\nif (platform() === 'darwin') await ensureSimulatorBooted(udid)\nelse await androidBackend.startSession(serial)","handlingStrategy":"validation","validationCode":"import { platform } from 'node:os'\nif (platform() !== 'darwin') { /* route to android or surface 'macOS required' */ }","typeGuard":"function isEmulatorError(e: unknown, code = 'emulator_not_macos'): e is import('./emulator-errors').EmulatorError {\n  return e instanceof Error && (e as any).code === code && e.name === 'EmulatorError'\n}","tryCatchPattern":"try { await ensureSimulatorBooted(udid) }\ncatch (e) { if (isEmulatorError(e, 'emulator_not_macos')) { /* use android backend */ } else throw e }","preventionTips":["Gate iOS emulator features behind a macOS host check.","Use the Android backend on Linux/Windows.","Install Xcode + Command Line Tools on macOS hosts."],"tags":["ios","macos","platform","simulator"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}