stablyai/orca · error · Error

Remote file download is unavailable. Reconnect the SSH targe

Error message

Remote file download is unavailable. Reconnect the SSH target and retry.

What it means

Thrown by the 'fs:downloadFile' IPC handler (src/main/ipc/filesystem.ts:650) after an SSH filesystem provider is resolved and the path is confirmed to be a file, but the provider has no optional 'downloadFile' method. SSH filesystem providers are registered per connectionId; a provider without 'downloadFile' is a limited/older remote relay that cannot stream files to the local machine.

Source

Thrown at src/main/ipc/filesystem.ts:650

      return { content: buffer.toString('utf-8'), isBinary: false }
    }
  )

  ipcMain.handle(
    'fs:downloadFile',
    async (
      event,
      args: { filePath?: string; connectionId?: string }
    ): Promise<DownloadFileResult> => {
      const filePath = validateRequiredString(args?.filePath, 'filePath')
      const connectionId = validateRequiredString(args?.connectionId, 'connectionId')
      const provider = requireSshFilesystemProvider(connectionId)
      const remoteStat = await provider.stat(filePath)
      if (remoteStat.type === 'directory') {
        throw new Error('Cannot download a directory')
      }
      if (!provider.downloadFile) {
        throw new Error('Remote file download is unavailable. Reconnect the SSH target and retry.')
      }

      const remoteBasename = getRuntimePathBasename(filePath)
      const defaultPath = sanitizeLocalDownloadFilename(remoteBasename)
      const parentWindow = BrowserWindow.fromWebContents(event.sender) ?? undefined
      const dialogResult = parentWindow
        ? await dialog.showSaveDialog(parentWindow, { defaultPath })
        : await dialog.showSaveDialog({ defaultPath })
      if (dialogResult.canceled || !dialogResult.filePath) {
        return { canceled: true }
      }

      const destinationPath = dialogResult.filePath
      const { existed } = await inspectDownloadDestination(destinationPath)
      const tempPath = createSiblingTransferPath(destinationPath, 'download')
      let promoted = false
      try {
        await provider.downloadFile(filePath, tempPath)

View on GitHub (pinned to 1136503c6a)

Solutions

  1. Reconnect the SSH target so a fresh handshake registers a current provider that implements downloadFile.
  2. Upgrade the remote Orca/relay build to a version that implements the downloadFile filesystem capability.
  3. Fall back to opening the remote file in the editor (fs:readFile) and saving its contents locally, or transfer the file out-of-band with scp/rsync.

Example fix

// before: invoke fs:downloadFile on a relay that lacks downloadFile
await window.api.invoke('fs:downloadFile', { filePath, connectionId })

// after: probe via readFile and persist locally when download is unavailable
try {
  return await window.api.invoke('fs:downloadFile', { filePath, connectionId })
} catch (e) {
  if (/download is unavailable/.test(e.message)) {
    const { content } = await window.api.invoke('fs:readFile', { filePath, connectionId })
    await saveLocalFile(basename(filePath), content)
  } else throw e
}
Defensive patterns

Strategy: try-catch

Validate before calling

// No stable IPC exposes provider.downloadFile capability; probe by attempting and catching.
// A heuristic pre-check: read a tiny prefix via fs:readFile to confirm the provider is responsive,
// but capability itself must be discovered at call time.
const responsive = await invoke('fs:stat', { filePath, connectionId }).then(() => true).catch(() => false)

Type guard

// Capability is runtime-only; no static type narrows it. Treat downloadFile as optional.
type MaybeDownloadProvider = { downloadFile?: (...args: unknown[]) => unknown }

Try / catch

try {
  return await invoke('fs:downloadFile', { filePath, connectionId })
} catch (e) {
  if (e instanceof Error && /download is unavailable/.test(e.message)) {
    // prompt reconnect, or fall back to fs:readFile + local save
  }
  throw e
}

Prevention

When it happens

Trigger: Calling ipcRenderer.invoke('fs:downloadFile', { filePath, connectionId }) where connectionId resolves to an IFilesystemProvider whose 'downloadFile' property is undefined. requireSshFilesystemProvider(connectionId) succeeds (so the connection is up) and provider.stat(filePath).type !== 'directory', but the capability check `if (!provider.downloadFile)` fires.

Common situations: The remote Orca relay/host is an older build that predates the downloadFile capability; a relay deployment that intentionally disables file streaming; the connectionId points at a provider implementation that never wired up download (e.g. a read-only viewer).

Related errors

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