{"record":{"id":"915bf27ca3c448c7","repo":"stablyai/orca","slug":"the-session-host-is-unavailable-reconnect-it-and","errorCode":null,"errorMessage":"The session host is unavailable. Reconnect it and retry resume.","messagePattern":"The session host is unavailable\\. Reconnect it and retry resume\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/main/ipc/ai-vault-resume.ts","lineNumber":30,"sourceCode":"    environmentId: string,\n    args: AiVaultPrepareSessionResumeArgs\n  ) => Promise<AiVaultPrepareSessionResumeResult>\n}\n\nexport function registerAiVaultResumeHandler(options: AiVaultResumeHandlerOptions): void {\n  ipcMain.handle('aiVault:prepareSessionResume', (_event, args: AiVaultPrepareSessionResumeArgs) =>\n    prepareAiVaultSessionResume(args, options)\n  )\n}\n\nexport async function prepareAiVaultSessionResume(\n  args: AiVaultPrepareSessionResumeArgs,\n  options: AiVaultResumeHandlerOptions\n): Promise<AiVaultPrepareSessionResumeResult> {\n  const executionHost = parseExecutionHostId(args.executionHostId)\n  if (executionHost?.kind === 'runtime') {\n    if (!options.prepareRuntimeSessionResume) {\n      throw new Error('The session host is unavailable. Reconnect it and retry resume.')\n    }\n    return options.prepareRuntimeSessionResume(executionHost.environmentId, args)\n  }\n  // Why: the desktop process must never materialize transcript paths owned by an SSH host.\n  if (executionHost?.kind === 'ssh') {\n    return { useRealCodexHome: false }\n  }\n  return options.prepareSessionResume?.(args) ?? { useRealCodexHome: false }\n}\n","sourceCodeStart":12,"sourceCodeEnd":40,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/ipc/ai-vault-resume.ts#L12-L40","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"function runtimeResumeAvailable(options: AiVaultResumeHandlerOptions): boolean {\n  return typeof options.prepareRuntimeSessionResume === 'function'\n}","typeGuard":"function isRuntimeResumeReady(options: AiVaultResumeHandlerOptions): options is AiVaultResumeHandlerOptions & { prepareRuntimeSessionResume: NonNullable<AiVaultResumeHandlerOptions['prepareRuntimeSessionResume']> } {\n  return typeof options.prepareRuntimeSessionResume === 'function'\n}","tryCatchPattern":"try {\n  return await prepareAiVaultSessionResume(args, options)\n} catch (error) {\n  if (error instanceof Error && /session host is unavailable/.test(error.message)) {\n    await reconnectRuntime()\n    return await prepareAiVaultSessionResume(args, refreshedOptions)\n  }\n  throw error\n}","preventionTips":["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."],"tags":["runtime","session","resume","connection","ai-vault"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}