stablyai/orca · error

SSH connection "${args.targetId}" not found

Error message

SSH connection "${args.targetId}" not found

What it means

Thrown by the 'ssh:addPortForward' IPC handler when connectionManager.getConnection(args.targetId) returns falsy. Port forwarding requires a live underlying SSH connection (the node-ssh/transport channel) to open the tunnel; without it, portForwardManager.addForward has nothing to bind to. The guard fails fast rather than letting addForward throw a less clear internal error.

Source

Thrown at src/main/ipc/ssh.ts:1526

  })

  // ── Port forwarding ─────────────────────────────────────────────────

  ipcMain.handle(
    'ssh:addPortForward',
    async (
      _event,
      args: {
        targetId: string
        localPort: number
        remoteHost: string
        remotePort: number
        label?: string
      }
    ) => {
      const conn = connectionManager!.getConnection(args.targetId)
      if (!conn) {
        throw new Error(`SSH connection "${args.targetId}" not found`)
      }
      const entry = await portForwardManager!.addForward(
        args.targetId,
        conn,
        args.localPort,
        args.remoteHost,
        args.remotePort,
        args.label
      )
      persistPortForwards(args.targetId)
      broadcastPortForwards(getCurrentMainWindow, args.targetId)
      return entry
    }
  )

  ipcMain.handle(
    'ssh:updatePortForward',
    async (

View on GitHub (pinned to 1136503c6a)

Solutions

1. Ensure the SSH target is fully connected (await connect) before adding a port forward.
2. If auto-restoring saved forwards, queue them until the connection-ready event fires.
3. Surface the disconnected state in the UI so the user connects first.

Example fix

// before
ipcRenderer.invoke('ssh:addPortForward', { targetId, localPort, remoteHost, remotePort })
// after
await ipcRenderer.invoke('ssh:connect', { targetId })
ipcRenderer.invoke('ssh:addPortForward', { targetId, localPort, remoteHost, remotePort })

const state = await ipcRenderer.invoke('ssh:getState', { targetId })
if (state.status !== 'connected') {
  await ipcRenderer.invoke('ssh:connect', { targetId })
}
await ipcRenderer.invoke('ssh:addPortForward', { targetId, localPort, remoteHost, remotePort })

try {
  await ipcRenderer.invoke('ssh:addPortForward', { targetId, localPort, remoteHost, remotePort })
} catch (e) {
  if (/SSH connection .* not found/.test((e as Error).message)) {
    await ipcRenderer.invoke('ssh:connect', { targetId })
    await ipcRenderer.invoke('ssh:addPortForward', { targetId, localPort, remoteHost, remotePort })
  } else throw e
}

When it happens

Trigger: Renderer invokes addPortForward for a targetId that is not currently connected — either never connected, disconnected, or mid-reconnect. The connectionManager has no Connection object keyed by that targetId at the moment of the call.

Common situations: User tries to add a forward before the SSH session finishes connecting. The connection dropped and the renderer did not yet reflect the disconnected state. A saved-forward auto-restore fires on startup before the session is live.

Related errors

• SSH target "${targetId}" not found
• SSH target "${args.targetId}" not found
• SSH target "${input.target.connectionId}" is not connected.
• SSH target did not connect: ${state.status}
• Remote connection dropped. Click Reconnect on the SSH target

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