stablyai/orca · error · Error

Remote folder download is unavailable. Reconnect the SSH tar

Error message

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

What it means

Thrown by the 'fs:downloadFolder' handler when requireSshFilesystemProvider(connectionId) returns a provider but that provider has no downloadFolder method. The SSH filesystem provider is registered per-connection, and not every transport/provider variant implements recursive folder download (it is an optional capability on IFilesystemProvider). The message tells the user to reconnect because a fresh connection typically rebuilds a full-capability provider.

Source

Thrown at src/main/ipc/filesystem-download-folder.ts:60

    // Why: cleanup must not mask the transfer error, but a leaked recursive
    // download tree needs enough visibility to diagnose and remove it.
    console.warn(`[filesystem] Failed to remove temporary folder download '${dirPath}'`, error)
  }
}

// Why: keep folder-download IPC out of filesystem.ts — that module is already large.
export function registerFilesystemDownloadFolderHandlers(): void {
  ipcMain.handle(
    'fs:downloadFolder',
    async (
      event,
      args: { dirPath?: string; connectionId?: string }
    ): Promise<DownloadFolderResult> => {
      const dirPath = validateRequiredString(args?.dirPath, 'dirPath')
      const connectionId = validateRequiredString(args?.connectionId, 'connectionId')
      const provider = requireSshFilesystemProvider(connectionId)
      if (!provider.downloadFolder) {
        throw new Error(
          'Remote folder download is unavailable. Reconnect the SSH target and retry.'
        )
      }
      const abortController = new AbortController()
      const abortOnSenderDestroyed = (): void => {
        abortController.abort(new Error('Folder download canceled because the window closed'))
      }
      event.sender.once('destroyed', abortOnSenderDestroyed)
      if (event.sender.isDestroyed()) {
        abortOnSenderDestroyed()
      }
      try {
        abortController.signal.throwIfAborted()
        const remoteBasename = getRuntimePathBasename(dirPath)
        const destinationBasename = sanitizeLocalDownloadFilename(remoteBasename)
        const parentWindow = BrowserWindow.fromWebContents(event.sender) ?? undefined
        // Why: after the local capability/abort checks, open the picker before
        // remote tree validation so SSH latency does not delay click feedback.

View on GitHub (pinned to 1136503c6a)

Solutions

1. Click Reconnect on the SSH target so a fresh, full-capability provider is registered for the connection.
2. If reconnect still yields a provider without downloadFolder, the chosen transport does not support folder downloads — switch to a transport that does or use per-file download.
3. Download individual files instead of the folder if the capability is unavailable for this target.

// Before invoking downloadFolder, confirm the live provider exposes the capability
import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
function canDownloadFolder(connectionId: string): boolean {
  const p = getSshFilesystemProvider(connectionId)
  return !!p && typeof p.downloadFolder === 'function'
}

function providerSupportsFolderDownload(p: unknown): p is { downloadFolder: Function } {
  return !!p && typeof (p as any).downloadFolder === 'function'
}

try {
  await window.api.fs.downloadFolder({ dirPath, connectionId })
} catch (e) {
  if (e instanceof Error && /unavailable/i.test(e.message)) {
    await reconnectSshTarget(connectionId)
    // optionally retry once
  } else throw e
}

When it happens

Trigger: A connectionId resolves to a provider object that lacks the downloadFolder capability — e.g. a relay/system-SSH provider variant, a degraded provider after a partial reconnect, or a provider registered for a transport that only supports file ops.

Common situations: The SSH target was reconnected with a different/limited transport (ProxyCommand/FIDO2/system-SSH fallback) that does not implement folder download; a provider version skew between client and host; the connection is mid-migration and registered a stub provider.

Related errors

• Remote file upload is unavailable. Reconnect the SSH target
• Only Hermes cron creation and editing are supported.
• Destination folder already exists
• Cannot download a directory
• Remote file download is unavailable. Reconnect the SSH targe

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