{"record":{"id":"f643481379db45d4","repo":"stablyai/orca","slug":"ssh-connection-is-not-available-please-reconnect","errorCode":null,"errorMessage":"SSH connection is not available. Please reconnect and try again.","messagePattern":"SSH connection is not available\\. Please reconnect and try again\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/main/ipc/ssh-worktree-create-root-registration.ts","lineNumber":47,"sourceCode":"\nexport async function registerOptionalSshWorktreeCreateRoots(\n  connectionId: string,\n  rootPaths: string[]\n): Promise<void> {\n  const mux = getActiveMultiplexer(connectionId)\n  if (!mux) {\n    return\n  }\n  await registerSshWorktreeCreateRoots(mux, rootPaths)\n}\n\nexport async function registerRequiredSshWorktreeCreateRoots(\n  connectionId: string,\n  rootPaths: string[]\n): Promise<void> {\n  const mux = getActiveMultiplexer(connectionId)\n  if (!mux) {\n    throw new Error(SSH_CONNECTION_UNAVAILABLE_MESSAGE)\n  }\n  await registerSshWorktreeCreateRoots(mux, rootPaths)\n}\n","sourceCodeStart":29,"sourceCodeEnd":51,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/ipc/ssh-worktree-create-root-registration.ts#L29-L51","documentation":"Thrown by registerRequiredSshWorktreeCreateRoots when getActiveMultiplexer(connectionId) returns a falsy value, meaning there is no live SSH mux (the multiplexed control connection) for the given connectionId. The 'required' variant exists because registering worktree-create roots on the remote host is mandatory for that flow to function, unlike the softer best-effort registration that just returns early. The error surfaces that the SSH session the caller believes is live has actually gone away.","triggerScenarios":"registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths) is called for a connectionId whose mux was disposed, never connected, or torn down after a relay disconnect/reconnect cycle. Typical during automated flows (post-connect setup) that race with a concurrent disconnect.","commonSituations":"A reconnect finished (mux replaced/disposed) while a deferred setup task still holds the old connectionId. The user disconnected an SSH target mid-operation. A stale connectionId was persisted and replayed on startup before the session re-established.","solutions":["Reconnect the SSH target, then retry the worktree-create-root registration so a fresh mux is available.","Guard the caller: check getActiveMultiplexer(connectionId) returns truthy before invoking the required variant, and skip or queue if not.","Ensure this call is sequenced after a successful connect completes (await the connect promise) rather than fired speculatively."],"exampleFix":"// before\nawait registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths)\n// after\nif (getActiveMultiplexer(connectionId)) {\n  await registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths)\n} else {\n  await reconnectTarget(connectionId)\n  await registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths)\n}","handlingStrategy":"validation","validationCode":"if (!getActiveMultiplexer(connectionId)) {\n  await reconnectTarget(connectionId)\n}\nawait registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths)","typeGuard":"function hasActiveMux(connectionId: string): boolean {\n  return getActiveMultiplexer(connectionId) !== undefined && !getActiveMultiplexer(connectionId)?.isDisposed()\n}","tryCatchPattern":"try {\n  await registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths)\n} catch (e) {\n  if (/SSH connection is not available/.test((e as Error).message)) {\n    await reconnectTarget(connectionId)\n    await registerRequiredSshWorktreeCreateRoots(connectionId, rootPaths)\n  } else throw e\n}","preventionTips":["Sequence worktree-create-root registration after the connect promise resolves.","Treat a disposed mux as a trigger to reconnect before retrying required setup steps.","Avoid holding connectionId across long awaits without re-validating the mux."],"tags":["ssh","connection","worktree","race-condition","multiplexer"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}