The session host is unavailable. Reconnect it and retry resu

Error message

The session host is unavailable. Reconnect it and retry resume.

What it means

Thrown by prepareAiVaultSessionResume when the execution host is a 'runtime' host (remote Orca runtime environment) but no prepareRuntimeSessionResume handler was registered in AiVaultResumeHandlerOptions. The runtime host's resume preparer is injected at connection time, so its absence means the runtime connection is down or was never wired into the resume handler.

Source

Thrown at src/main/ipc/ai-vault-resume.ts:30

    environmentId: string,
    args: AiVaultPrepareSessionResumeArgs
  ) => Promise<AiVaultPrepareSessionResumeResult>
}

export function registerAiVaultResumeHandler(options: AiVaultResumeHandlerOptions): void {
  ipcMain.handle('aiVault:prepareSessionResume', (_event, args: AiVaultPrepareSessionResumeArgs) =>
    prepareAiVaultSessionResume(args, options)
  )
}

export async function prepareAiVaultSessionResume(
  args: AiVaultPrepareSessionResumeArgs,
  options: AiVaultResumeHandlerOptions
): Promise<AiVaultPrepareSessionResumeResult> {
  const executionHost = parseExecutionHostId(args.executionHostId)
  if (executionHost?.kind === 'runtime') {
    if (!options.prepareRuntimeSessionResume) {
      throw new Error('The session host is unavailable. Reconnect it and retry resume.')
    }
    return options.prepareRuntimeSessionResume(executionHost.environmentId, args)
  }
  // Why: the desktop process must never materialize transcript paths owned by an SSH host.
  if (executionHost?.kind === 'ssh') {
    return { useRealCodexHome: false }
  }
  return options.prepareSessionResume?.(args) ?? { useRealCodexHome: false }
}

View on GitHub (pinned to 1136503c6a)

Solutions

Reconnect to the runtime host, then retry the resume — the handler is re-registered on connect.
Verify the executionHostId still corresponds to a live runtime environment.
If the runtime is permanently unavailable, resume a local session instead.

Defensive patterns

Strategy: try-catch

Validate before calling

function runtimeResumeAvailable(options: AiVaultResumeHandlerOptions): boolean {
  return typeof options.prepareRuntimeSessionResume === 'function'
}

Type guard

function isRuntimeResumeReady(options: AiVaultResumeHandlerOptions): options is AiVaultResumeHandlerOptions & { prepareRuntimeSessionResume: NonNullable<AiVaultResumeHandlerOptions['prepareRuntimeSessionResume']> } {
  return typeof options.prepareRuntimeSessionResume === 'function'
}

Try / catch

try {
  return await prepareAiVaultSessionResume(args, options)
} catch (error) {
  if (error instanceof Error && /session host is unavailable/.test(error.message)) {
    await reconnectRuntime()
    return await prepareAiVaultSessionResume(args, refreshedOptions)
  }
  throw error
}

Prevention

Register the runtime resume handler on every runtime connect, and clear it on disconnect.
Before offering 'resume' in the UI for runtime sessions, check the connection is live.

When it happens

Trigger: Resuming an AI session whose executionHostId parses to kind 'runtime', while the runtime connection that would supply prepareRuntimeSessionResume has been closed/cleared. The desktop process cannot resume a runtime session without the runtime bridge.

Common situations: Runtime/remote Orca server disconnected before resume; the resume handler was registered before the runtime connected; runtime crashed or was restarted; executionHostId points at a stale runtime environment ID.

Related errors

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