stablyai/orca · error · RuntimeClientError

runtime_open_timeout

runtime_open_timeout

Error message

Timed out waiting for an Orca desktop window. The runtime may still be running headlessly.

What it means

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.

Source

Thrown at src/cli/runtime/client.ts:243

    }
    launchOrcaApp()
    if (initial.result.app.desktopWindowStatus === 'available') {
      return initial
    }

    const startedAt = Date.now()
    while (Date.now() - startedAt < timeoutMs) {
      const status = await this.getCliStatus()
      if (status.result.app.desktopWindowStatus === 'blocked') {
        throwDesktopActivationBlocked()
      }
      if (status.result.app.desktopWindowStatus === 'available') {
        return status
      }
      await delay(250)
    }

    throw new RuntimeClientError(
      'runtime_open_timeout',
      'Timed out waiting for an Orca desktop window. The runtime may still be running headlessly.'
    )
  }
}

function attachMutationRecovery(error: unknown, requestId: string | undefined): unknown {
  if (!requestId || !(error instanceof RuntimeClientError)) {
    return error
  }
  return new RuntimeClientError(
    error.code,
    `${error.message} Orchestration mutation request ID: ${requestId}.`,
    {
      ...(error.data && typeof error.data === 'object' ? error.data : {}),
      orchestrationRequestId: requestId
    }
  )

View on GitHub (pinned to 1136503c6a)

Solutions

1. Increase the timeout if you pass timeoutMs: `openOrca(60_000)` or the equivalent CLI flag.
2. Ensure a display is available (set DISPLAY / run locally / forward X11).
3. If headless is intended, use the headless/serve mode instead of requesting a desktop window.
4. Restart Orca if it is hung.

Example fix

// before
const status = await client.openOrca()
// after
const status = await client.openOrca(60_000)

// No synchronous validation possible; pre-check display availability.
const hasDisplay = !!process.env.DISPLAY || process.platform === 'darwin' || process.platform === 'win32'
if (!hasDisplay) throw new Error('No display available; use serve/headless mode')

function likelyHasDisplay(): boolean {
  return process.platform === 'darwin' || process.platform === 'win32' || Boolean(process.env.DISPLAY)
}

try {
  await runtimeClient.openOrca(timeoutMs)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'runtime_open_timeout') {
    // fall back to headless/serve mode or prompt user to start Orca manually
  } else throw e
}

When it happens

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

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

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• desktop_activation_blocked
• [plain-node-entry-guard] daemon-entry.js did not exit within
• Benchmark workload exceeded the ${maxWorkloadOverrunMs}ms sa
• Timed out polling renderer diagnostics after ${pollTimeoutMs
• Timed out polling ${label} after ${pollTimeoutMs}ms.

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