{"record":{"id":"7148b0ef1b1dcafa","repo":"stablyai/orca","slug":"emulator-helper-failed-7148b0","errorCode":"emulator_helper_failed","errorMessage":"serve-sim AX request failed (${response.status}): ${detail}.${retry}","messagePattern":"serve-sim AX request failed \\((.+?)\\): (.+?)\\.(.+?)","errorType":"exception","errorClass":"EmulatorError","httpStatus":null,"severity":"error","filePath":"src/main/emulator/serve-sim-accessibility-tree.ts","lineNumber":17,"sourceCode":"import { net } from 'electron'\nimport { EmulatorError } from './emulator-errors'\nimport { normalizeServeSimAxTree, type NormalizedAxNode } from './serve-sim-ax-normalization'\n\nconst AX_REQUEST_TIMEOUT_MS = 5_000\nconst MAX_ERROR_BODY_LENGTH = 512\n\nexport async function requestServeSimAccessibilityTree(axUrl: string): Promise<NormalizedAxNode[]> {\n  try {\n    const response = await net.fetch(axUrl, {\n      signal: AbortSignal.timeout(AX_REQUEST_TIMEOUT_MS)\n    })\n    const body = await response.text()\n    if (!response.ok) {\n      const detail = body.slice(0, MAX_ERROR_BODY_LENGTH) || response.statusText\n      const retry = response.status === 503 ? ' Accessibility may still be warming up; retry.' : ''\n      throw new EmulatorError(\n        'emulator_helper_failed',\n        `serve-sim AX request failed (${response.status}): ${detail}.${retry}`\n      )\n    }\n\n    let tree: unknown\n    try {\n      tree = JSON.parse(body)\n    } catch {\n      throw new EmulatorError('emulator_error', 'serve-sim AX returned invalid JSON.')\n    }\n    if (\n      !Array.isArray(tree) ||\n      tree.some((node) => typeof node !== 'object' || node === null || Array.isArray(node))\n    ) {\n      throw new EmulatorError('emulator_error', 'serve-sim AX returned an invalid tree.')\n    }\n    // serve-sim reports frames in absolute pixels; normalize to 0..1 so the","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/emulator/serve-sim-accessibility-tree.ts#L1-L35","documentation":"requestServeSimAccessibilityTree received an HTTP response with a non-2xx status from the serve-sim /ax endpoint. For 503 the message appends a 'warming up, retry' hint because the accessibility service often is not ready immediately after boot.","triggerScenarios":"net.fetch(axUrl) returns response.ok === false (serve-sim-accessibility-tree.ts:14-20). The first 512 bytes of the body (or statusText) become the detail; status 503 adds the retry suffix.","commonSituations":"Calling accessibilityTree right after attach (AX not yet warm); serve-sim internal error; simulator still mid-boot; the /ax endpoint temporarily overloaded.","solutions":["Retry accessibilityTree after a short delay (the 503 case is explicitly retryable).","Ensure `orca emulator attach` completed and the simulator finished booting before the first AX read.","Check serve-sim logs for the status detail embedded in the error message."],"exampleFix":"// before\nawait requestServeSimAccessibilityTree(axUrl) // 503 right after boot\n\n// after\nawait waitForSimulatorBooted(udid)\nawait retry(() => requestServeSimAccessibilityTree(axUrl), { tries: 3, delayMs: 500 })","handlingStrategy":"retry","validationCode":"const probe = await fetch(axUrl, { signal: AbortSignal.timeout(1000) }).catch(() => null)\nif (probe && probe.status === 503) { /* AX still warming up; wait then call */ }","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 { return await requestServeSimAccessibilityTree(axUrl) }\ncatch (e) {\n  if (isEmulatorError(e) && /503|warming up/.test(e.message)) { await delay(500); return await requestServeSimAccessibilityTree(axUrl) }\n  throw e\n}","preventionTips":["Wait for boot to settle before the first AX read.","Treat 503 as retryable.","Surface the embedded status/body detail when reporting the error."],"tags":["ios","accessibility","serve-sim","http","retry"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}