{"record":{"id":"0a585643b1cf613e","repo":"stablyai/orca","slug":"emulator-helper-failed-0a5856","errorCode":"emulator_helper_failed","errorMessage":"Simulator ${udid} keeps booting without a working display (no framebuffer descriptor), even after a reboot. Erase it with `xcrun simctl erase ${udid}` or recreate it in Xcode > Window > Devices and Simulators.\n\n${error.message}","messagePattern":"Simulator (.+?) keeps booting without a working display \\(no framebuffer descriptor\\), even after a reboot\\. Erase it with `xcrun simctl erase (.+?)` or recreate it in Xcode > Window > Devices and Simulators\\.\n\n(.+?)","errorType":"exception","errorClass":"EmulatorError","httpStatus":null,"severity":"error","filePath":"src/main/emulator/backends/ios-emulator-backend.ts","lineNumber":212,"sourceCode":"      return parseServeSimDetachedSession(raw, udid)\n    }\n\n    const waitForReadyOrKill = async (info: EmulatorSessionInfo): Promise<boolean> => {\n      if (\n        (await this.waitForEndpointReady(info.streamUrl)) &&\n        (await this.hasHelperForSession(info))\n      ) {\n        return true\n      }\n      await this.stopHelperForDevice(info.deviceUdid, {\n        helperPid: info.helperPid,\n        includeOrphaned: true\n      })\n      return false\n    }\n\n    const throwPersistentMissingFramebuffer = (error: EmulatorError): never => {\n      throw new EmulatorError(\n        'emulator_helper_failed',\n        `Simulator ${udid} keeps booting without a working display (no framebuffer descriptor), even after a reboot. Erase it with \\`xcrun simctl erase ${udid}\\` or recreate it in Xcode > Window > Devices and Simulators.\\n\\n${error.message}`\n      )\n    }\n\n    // Why: CoreSimulator can report \"Booted\" with the display IO ports down\n    // (HID alive, no framebuffer); a shutdown/boot recycle is the only recovery.\n    let didRecycleWedgedBoot = false\n    const startHelperRecyclingWedgedBoot = async (): Promise<EmulatorSessionInfo> => {\n      try {\n        return await startDetachedHelper()\n      } catch (error) {\n        if (!isMissingFramebufferError(error)) {\n          throw error\n        }\n        if (didRecycleWedgedBoot) {\n          return throwPersistentMissingFramebuffer(error)\n        }","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/emulator/backends/ios-emulator-backend.ts#L194-L230","documentation":"Thrown by IosEmulatorBackend.startSession after it already shut down and re-booted the simulator once (the didRecycleWedgedBoot gate) and the serve-sim helper STILL reports a missing framebuffer. CoreSimulator claims state 'Booted' while the display IO ports are down (HID alive, no framebuffer descriptor), so the simulator is wedged beyond what an in-process recycle can fix.","triggerScenarios":"startDetachedHelper() throws an error matching isMissingFramebufferError on the first attempt AND again after startHelperRecyclingWedgedBoot runs shutdownSimulatorDevice(udid)+ensureSimulatorBooted(udid). Only at that second failure (or when didRecycleWedgedBoot is already true) is throwPersistentMissingFramebuffer invoked (ios-emulator-backend.ts:211-243).","commonSituations":"Simulator left half-booted after a crash/force-quit of Simulator.app, corrupted simulator runtime data, an Xcode/Simulator.app upgrade landed mid-session, disk pressure stalling the CoreSimulator framebuffer service, or a stale CoreSimulatorService daemon.","solutions":["Run `xcrun simctl erase <udid>` to wipe the simulator data, then re-attach with `orca emulator attach <udid>`.","If erase fails, delete and recreate the device in Xcode > Window > Devices and Simulators.","Reset CoreSimulator: `xcrun simctl shutdown all` then `killall com.apple.CoreSimulator.CoreSimulatorService`, restart, retry.","Free disk space / reboot macOS if the framebuffer service itself is unresponsive."],"exampleFix":"// before\nawait bridge.startSession(udid) // throws: keeps booting, no framebuffer\n\n// after (shell recovery)\n// xcrun simctl erase <udid>\nawait bridge.startSession(udid)","handlingStrategy":"try-catch","validationCode":"const state = await listSimulatorDevices().find(d => d.udid === udid);\nif (state && state.state !== 'Booted') { /* boot first */ }","typeGuard":"function isEmulatorError(e: unknown, code = 'emulator_helper_failed'): e is import('./emulator-errors').EmulatorError {\n  return e instanceof Error && (e as any).code === code && e.name === 'EmulatorError'\n}","tryCatchPattern":"try { await bridge.startSession(udid) }\ncatch (e) {\n  if (isEmulatorError(e) && /no framebuffer/.test(e.message)) { await eraseAndRetry(udid) }\n  else throw e\n}","preventionTips":["Avoid force-quitting Simulator.app while a session is live.","After an Xcode upgrade, boot each simulator once in Simulator.app before attaching from Orca.","Keep free disk space; the framebuffer service stalls under disk pressure."],"tags":["ios","simulator","core-simulator","framebuffer","macos"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}