stablyai/orca · error · EmulatorError

emulator_helper_failed

emulator_helper_failed

Error message

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.

${error.message}

What it means

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.

Source

Thrown at src/main/emulator/backends/ios-emulator-backend.ts:212

      return parseServeSimDetachedSession(raw, udid)
    }

    const waitForReadyOrKill = async (info: EmulatorSessionInfo): Promise<boolean> => {
      if (
        (await this.waitForEndpointReady(info.streamUrl)) &&
        (await this.hasHelperForSession(info))
      ) {
        return true
      }
      await this.stopHelperForDevice(info.deviceUdid, {
        helperPid: info.helperPid,
        includeOrphaned: true
      })
      return false
    }

    const throwPersistentMissingFramebuffer = (error: EmulatorError): never => {
      throw new EmulatorError(
        'emulator_helper_failed',
        `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}`
      )
    }

    // Why: CoreSimulator can report "Booted" with the display IO ports down
    // (HID alive, no framebuffer); a shutdown/boot recycle is the only recovery.
    let didRecycleWedgedBoot = false
    const startHelperRecyclingWedgedBoot = async (): Promise<EmulatorSessionInfo> => {
      try {
        return await startDetachedHelper()
      } catch (error) {
        if (!isMissingFramebufferError(error)) {
          throw error
        }
        if (didRecycleWedgedBoot) {
          return throwPersistentMissingFramebuffer(error)
        }

View on GitHub (pinned to 1136503c6a)

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.

Example fix

// before
await bridge.startSession(udid) // throws: keeps booting, no framebuffer

// after (shell recovery)
// xcrun simctl erase <udid>
await bridge.startSession(udid)

Defensive patterns

Strategy: try-catch

Validate before calling

const state = await listSimulatorDevices().find(d => d.udid === udid);
if (state && state.state !== 'Booted') { /* boot first */ }

Type guard

function isEmulatorError(e: unknown, code = 'emulator_helper_failed'): e is import('./emulator-errors').EmulatorError {
  return e instanceof Error && (e as any).code === code && e.name === 'EmulatorError'
}

Try / catch

try { await bridge.startSession(udid) }
catch (e) {
  if (isEmulatorError(e) && /no framebuffer/.test(e.message)) { await eraseAndRetry(udid) }
  else throw e
}

Prevention

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.

When it happens

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

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

Related errors

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