{"record":{"id":"57dd6e2a9fd320da","repo":"stablyai/orca","slug":"runtime-open-timeout","errorCode":"runtime_open_timeout","errorMessage":"Timed out waiting for an Orca desktop window. The runtime may still be running headlessly.","messagePattern":"Timed out waiting for an Orca desktop window\\. The runtime may still be running headlessly\\.","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/runtime/client.ts","lineNumber":243,"sourceCode":"    }\n    launchOrcaApp()\n    if (initial.result.app.desktopWindowStatus === 'available') {\n      return initial\n    }\n\n    const startedAt = Date.now()\n    while (Date.now() - startedAt < timeoutMs) {\n      const status = await this.getCliStatus()\n      if (status.result.app.desktopWindowStatus === 'blocked') {\n        throwDesktopActivationBlocked()\n      }\n      if (status.result.app.desktopWindowStatus === 'available') {\n        return status\n      }\n      await delay(250)\n    }\n\n    throw new RuntimeClientError(\n      'runtime_open_timeout',\n      'Timed out waiting for an Orca desktop window. The runtime may still be running headlessly.'\n    )\n  }\n}\n\nfunction attachMutationRecovery(error: unknown, requestId: string | undefined): unknown {\n  if (!requestId || !(error instanceof RuntimeClientError)) {\n    return error\n  }\n  return new RuntimeClientError(\n    error.code,\n    `${error.message} Orchestration mutation request ID: ${requestId}.`,\n    {\n      ...(error.data && typeof error.data === 'object' ? error.data : {}),\n      orchestrationRequestId: requestId\n    }\n  )","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/runtime/client.ts#L225-L261","documentation":"Thrown by openOrca after polling getCliStatus for up to `timeoutMs` (default 15s) without the desktop window reaching 'available'. The loop also short-circuits to a desktop_activation_blocked error if the status becomes 'blocked'. Reaching the timeout means Orca is likely running headlessly or the window never came up; the error explicitly notes headless running as a possibility.","triggerScenarios":"Invoking openOrca on a machine where Orca is running without a GUI (headless), where the window is slow to initialize, or where the desktop environment cannot display it. Polling status.result.app.desktopWindowStatus stays non-'available' for the whole window.","commonSituations":"Running the CLI over SSH without X11/Wayland forwarding. CI runners with no display. A slow first-launch where window initialization exceeds 15s. A hung Orca process that reports neither 'available' nor 'blocked'.","solutions":["Increase the timeout if you pass timeoutMs: `openOrca(60_000)` or the equivalent CLI flag.","Ensure a display is available (set DISPLAY / run locally / forward X11).","If headless is intended, use the headless/serve mode instead of requesting a desktop window.","Restart Orca if it is hung."],"exampleFix":"// before\nconst status = await client.openOrca()\n// after\nconst status = await client.openOrca(60_000)","handlingStrategy":"try-catch","validationCode":"// No synchronous validation possible; pre-check display availability.\nconst hasDisplay = !!process.env.DISPLAY || process.platform === 'darwin' || process.platform === 'win32'\nif (!hasDisplay) throw new Error('No display available; use serve/headless mode')","typeGuard":"function likelyHasDisplay(): boolean {\n  return process.platform === 'darwin' || process.platform === 'win32' || Boolean(process.env.DISPLAY)\n}","tryCatchPattern":"try {\n  await runtimeClient.openOrca(timeoutMs)\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'runtime_open_timeout') {\n    // fall back to headless/serve mode or prompt user to start Orca manually\n  } else throw e\n}","preventionTips":["Ensure a display is available before requesting a desktop window.","Use a longer timeoutMs for slow first-launches.","Prefer serve/headless mode in CI and SSH contexts."],"tags":["runtime","desktop-window","timeout","headless","async"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}