{"record":{"id":"4c8008367f0b58a8","repo":"stablyai/orca","slug":"action-timeout","errorCode":"action_timeout","errorMessage":"native macOS helper app did not open its socket: ${lastError?.message ?? 'timed out'}","messagePattern":"native macOS helper app did not open its socket: (.+?)","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/main/computer/macos-native-provider-socket.ts","lineNumber":28,"sourceCode":"  let lastError: Error | null = null\n  while (Date.now() < deadline && !signal?.aborted) {\n    try {\n      return await connectSocket(socketPath, signal)\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error))\n      if (signal?.aborted) {\n        break\n      }\n      await sleep(100, signal)\n    }\n  }\n  if (signal?.aborted) {\n    throw new RuntimeClientError(\n      'accessibility_error',\n      'native macOS helper app startup was cancelled'\n    )\n  }\n  throw new RuntimeClientError(\n    'action_timeout',\n    `native macOS helper app did not open its socket: ${lastError?.message ?? 'timed out'}`\n  )\n}\n\nfunction connectSocket(socketPath: string, signal?: AbortSignal): Promise<net.Socket> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(\n        new RuntimeClientError(\n          'accessibility_error',\n          'native macOS helper app startup was cancelled'\n        )\n      )\n      return\n    }\n    const socket = net.createConnection(socketPath)\n    const cleanup = (): void => {","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/computer/macos-native-provider-socket.ts#L10-L46","documentation":"connectMacOSProviderSocket's deadline (HELPER_CONNECT_TIMEOUT_MS, 10s) elapsed and no connectSocket attempt succeeded; the helper never opened its provider.sock. Reported as 'action_timeout' with the last connection error (or 'timed out'). The transport's catch will already have SIGTERM'd the detached helper.","triggerScenarios":"Helper spawned but blocked before binding its socket (TCC prompt hanging, slow first-launch signature validation, sandbox denial); socket permission/path mismatch between helper and client; helper silently exiting and respawning under a watchdog without ever binding.","commonSituations":"First run after install while macOS evaluates notarization/Gatekeeper; heavy system load making the helper's bind exceed 10s; SOCK path under a tmpdir with restrictive perms; security software interposing on Unix sockets.","solutions":["Retry the computer-use request — many first-run stalls are transient.","Inspect Console.app for the helper process (orca-computer-use-macos) for the bind failure or TCC prompt blocking it.","Grant Accessibility & Screen Recording to the helper up front via openComputerUsePermissions so first-launch prompts do not block the socket.","If reproducing in CI, raise HELPER_CONNECT_TIMEOUT_MS only after ruling out a real hang; otherwise investigate the helper's startup log."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"import { RuntimeClientError } from './runtime-client-error'\n\nfunction isHelperSocketTimeout(e: unknown): e is RuntimeClientError {\n  return (\n    e instanceof RuntimeClientError &&\n    e.code === 'action_timeout' &&\n    /did not open its socket/.test(e.message)\n  )\n}","tryCatchPattern":"try {\n  await client.listApps()\n} catch (e) {\n  if (isHelperSocketTimeout(e)) {\n    // one bounded retry; if it persists, escalate — first-launch TCC/Gatekeeper stalls need user action\n  } else throw e\n}","preventionTips":["Pre-grant Accessibility & Screen Recording to the helper to avoid first-launch TCC prompts blocking the socket.","Keep HELPER_CONNECT_TIMEOUT_MS realistic; raise only after ruling out a real hang.","Watch Console.app for orca-computer-use-macos when this recurs."],"tags":["macos","computer-use","socket","timeout","startup","action-timeout"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}