{"record":{"id":"600ac67157933fc3","repo":"stablyai/orca","slug":"remote-file-download-is-unavailable-reconnect-the","errorCode":null,"errorMessage":"Remote file download is unavailable. Reconnect the SSH target and retry.","messagePattern":"Remote file download is unavailable\\. Reconnect the SSH target and retry\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ipc/filesystem.ts","lineNumber":650,"sourceCode":"      return { content: buffer.toString('utf-8'), isBinary: false }\n    }\n  )\n\n  ipcMain.handle(\n    'fs:downloadFile',\n    async (\n      event,\n      args: { filePath?: string; connectionId?: string }\n    ): Promise<DownloadFileResult> => {\n      const filePath = validateRequiredString(args?.filePath, 'filePath')\n      const connectionId = validateRequiredString(args?.connectionId, 'connectionId')\n      const provider = requireSshFilesystemProvider(connectionId)\n      const remoteStat = await provider.stat(filePath)\n      if (remoteStat.type === 'directory') {\n        throw new Error('Cannot download a directory')\n      }\n      if (!provider.downloadFile) {\n        throw new Error('Remote file download is unavailable. Reconnect the SSH target and retry.')\n      }\n\n      const remoteBasename = getRuntimePathBasename(filePath)\n      const defaultPath = sanitizeLocalDownloadFilename(remoteBasename)\n      const parentWindow = BrowserWindow.fromWebContents(event.sender) ?? undefined\n      const dialogResult = parentWindow\n        ? await dialog.showSaveDialog(parentWindow, { defaultPath })\n        : await dialog.showSaveDialog({ defaultPath })\n      if (dialogResult.canceled || !dialogResult.filePath) {\n        return { canceled: true }\n      }\n\n      const destinationPath = dialogResult.filePath\n      const { existed } = await inspectDownloadDestination(destinationPath)\n      const tempPath = createSiblingTransferPath(destinationPath, 'download')\n      let promoted = false\n      try {\n        await provider.downloadFile(filePath, tempPath)","sourceCodeStart":632,"sourceCodeEnd":668,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/ipc/filesystem.ts#L632-L668","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Reconnect the SSH target so a fresh handshake registers a current provider that implements downloadFile.","Upgrade the remote Orca/relay build to a version that implements the downloadFile filesystem capability.","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."],"exampleFix":"// before: invoke fs:downloadFile on a relay that lacks downloadFile\nawait window.api.invoke('fs:downloadFile', { filePath, connectionId })\n\n// after: probe via readFile and persist locally when download is unavailable\ntry {\n  return await window.api.invoke('fs:downloadFile', { filePath, connectionId })\n} catch (e) {\n  if (/download is unavailable/.test(e.message)) {\n    const { content } = await window.api.invoke('fs:readFile', { filePath, connectionId })\n    await saveLocalFile(basename(filePath), content)\n  } else throw e\n}","handlingStrategy":"try-catch","validationCode":"// No stable IPC exposes provider.downloadFile capability; probe by attempting and catching.\n// A heuristic pre-check: read a tiny prefix via fs:readFile to confirm the provider is responsive,\n// but capability itself must be discovered at call time.\nconst responsive = await invoke('fs:stat', { filePath, connectionId }).then(() => true).catch(() => false)","typeGuard":"// Capability is runtime-only; no static type narrows it. Treat downloadFile as optional.\ntype MaybeDownloadProvider = { downloadFile?: (...args: unknown[]) => unknown }","tryCatchPattern":"try {\n  return await invoke('fs:downloadFile', { filePath, connectionId })\n} catch (e) {\n  if (e instanceof Error && /download is unavailable/.test(e.message)) {\n    // prompt reconnect, or fall back to fs:readFile + local save\n  }\n  throw e\n}","preventionTips":["After SSH reconnect, re-issue the download rather than reusing a stale call.","Keep the remote Orca/relay build current so downloadFile is implemented.","Show the download action only for connection types known to support it."],"tags":["ssh","remote-files","ipc","capability","electron"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}