stablyai/orca · error

Automation workspace was created, but no agent terminal star

Error message

Automation workspace was created, but no agent terminal started.

What it means

Thrown during automation-run startup when the workspace/worktree was created successfully but the returned startupTerminal has no handle (empty string) and the creator supplied no warning text. This is the fallback message indicating the agent terminal failed to start even though the workspace exists — a partial-success state that the caller cannot safely proceed from.

Source

Thrown at src/main/index.ts:2589

          let workspaceId: string
          let workspaceDisplayName: string | null = null

          if (automation.workspaceMode === 'new_per_run') {
            const created = await runtimeService.createManagedWorktree({
              ...buildHeadlessAutomationWorktreeCreateArgs({
                automation,
                run,
                repo: target.repo
              })
            })
            terminalHandle = created.startupTerminal?.handle ?? ''
            terminalSessionId = created.startupTerminal?.tabId ?? null
            terminalPaneKey = created.startupTerminal?.paneKey ?? null
            terminalPtyId = created.startupTerminal?.ptyId ?? null
            workspaceId = created.worktree.id
            workspaceDisplayName = created.worktree.displayName ?? null
            if (!terminalHandle) {
              throw new Error(
                created.warning ||
                  'Automation workspace was created, but no agent terminal started.'
              )
            }
          } else {
            if (!automation.workspaceId) {
              throw new Error('The target workspace is no longer available.')
            }
            const terminal = await runtimeService.launchAgentTerminal(
              `id:${automation.workspaceId}`,
              {
                agent: automation.agentId,
                prompt: automation.prompt,
                title: run.title
              }
            )
            terminalHandle = terminal.handle
            terminalSessionId = terminal.tabId ?? null

View on GitHub (pinned to 1136503c6a)

Solutions

1. Retry the automation run after confirming the terminal/PTY subsystem is healthy.
2. Check the runtime logs for PTY spawn errors or terminal-service initialization failures.
3. Ensure the host has sufficient resources (PTY slots, file descriptors) before launching automation.
4. Report created.warning to the operator UI — if empty, file a bug since the creator should explain why no terminal started.

function hasTerminalHandle(created: unknown): created is { startupTerminal: { handle: string } } {
  return typeof created === 'object' && created !== null
    && typeof (created as any).startupTerminal?.handle === 'string'
    && (created as any).startupTerminal.handle.length > 0
}

try {
  await startAutomationRun(...)
} catch (error) {
  if (/no agent terminal started/.test(String((error as Error).message))) {
    await retryAfterHealthCheck() // verify PTY/terminal service, then retry
  } else throw error
}

When it happens

Trigger: createAutomationWorkspace (or equivalent) returns a created worktree but startupTerminal.handle is empty/null and created.warning is empty. Happens when the terminal subsystem (PTY) failed to spawn silently, the tab/pane creation returned an empty handle, or an internal error path neglected to populate the warning.

Common situations: PTY allocation failure on the host; terminal service not initialized at automation start; race where the workspace was created but the terminal manager was torn down; a bug in the workspace creator returning an incomplete terminal descriptor.

Related errors

• The target workspace is no longer available.
• terminal_pane_owner_unverified
• advertised-url-watcher.ts no longer contains \`${marker}\`
• Timed out polling ${label} after ${pollTimeoutMs}ms.
• Timed out waiting for ${label}; last value: ${JSON.stringify

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