{"record":{"id":"b534b42c14b056b7","repo":"stablyai/orca","slug":"relativepath-is-too-large-for-remote-import","errorCode":null,"errorMessage":"'${relativePath}' is too large for remote import","messagePattern":"'(.+?)' is too large for remote import","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ipc/filesystem-mutations.ts","lineNumber":651,"sourceCode":"): Promise<void> {\n  const candidateRealPath = await realpath(candidatePath)\n  const relativeToRoot = relative(rootRealPath, candidateRealPath)\n  // Why: `..name` is a valid child path; only `..` and `../...` escape.\n  if (\n    relativeToRoot !== '' &&\n    (relativeToRoot === '..' || relativeToRoot.startsWith(`..${sep}`) || isAbsolute(relativeToRoot))\n  ) {\n    throw new Error(`Path escaped upload root during staging: '${displayPath}'`)\n  }\n}\n\nfunction assertRemoteUploadBudget(\n  relativePath: string,\n  fileBytes: number,\n  totalBytes: number\n): void {\n  if (fileBytes > REMOTE_IMPORT_MAX_FILE_BYTES) {\n    throw new Error(`'${relativePath}' is too large for remote import`)\n  }\n  if (totalBytes > REMOTE_IMPORT_MAX_TOTAL_BYTES) {\n    throw new Error('Remote import is too large')\n  }\n}\n\nfunction normalizeRelativeUploadPath(path: string): string {\n  return path.replace(/[\\\\/]+/g, '/').replace(/^\\/+/, '')\n}\n\n/**\n * Pre-scan a directory tree for symlinks. Returns true if any symlink\n * is found anywhere in the subtree.\n */\nasync function preScanForSymlinks(dirPath: string): Promise<boolean> {\n  const entries = await readdir(dirPath, { withFileTypes: true })\n  for (const entry of entries) {\n    if (entry.isSymbolicLink()) {","sourceCodeStart":633,"sourceCodeEnd":669,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/ipc/filesystem-mutations.ts#L633-L669","documentation":"Thrown by assertRemoteUploadBudget when a single staged file exceeds REMOTE_IMPORT_MAX_FILE_BYTES (25 MB). Remote import encodes file contents as base64 inside IPC messages, so per-file size is capped to keep individual messages manageable.","triggerScenarios":"Calling the remote upload staging IPC with a file whose size exceeds 25 MB (25 * 1024 * 1024 bytes). The check runs on statResult.size before the file is buffered, so large files are rejected early.","commonSituations":"Trying to import a large binary, video, database dump, or archive into a remote SSH worktree. Exceeding the 25 MB cap with a minified bundle, compiled binary, or large dataset file.","solutions":["Exclude the large file from the import selection and transfer it separately (e.g., scp directly to the remote host).","Split or compress the file so it is under 25 MB before staging.","If importing a directory, remove or move the oversized file out of the source tree first."],"exampleFix":"// before: stage a 40MB file for remote import\n// after: transfer it directly and exclude from staging\n//   scp large.bin remote:/worktree/\n//   then import the remaining files without large.bin","handlingStrategy":"validation","validationCode":"const { stat } = await import('node:fs/promises')\nconst REMOTE_IMPORT_MAX_FILE_BYTES = 25 * 1024 * 1024\n\nasync function assertFileUnderRemoteLimit(filePath: string): Promise<void> {\n  const s = await stat(filePath)\n  if (s.size > REMOTE_IMPORT_MAX_FILE_BYTES) {\n    throw new Error(`${filePath} is ${(s.size / 1048576).toFixed(1)}MB, exceeds 25MB remote file limit`)\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await stageRemoteImport(sourcePath)\n} catch (error) {\n  if (error instanceof Error && error.message.includes('too large for remote import')) {\n    showUserError(error.message + ' — transfer this file directly via scp.')\n    return\n  }\n  throw error\n}","preventionTips":["Check file sizes with `ls -la` or `du -h` before staging for remote import.","Transfer files over 25 MB directly to the remote host via scp/rsync.","Split or compress large files before including them in the import set."],"tags":["size-limit","upload-staging","remote-import","ipc","filesystem"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}