stablyai/orca · error · Error

'${relativePath}' is too large for remote import

Error message

'${relativePath}' is too large for remote import

What it means

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.

Source

Thrown at src/main/ipc/filesystem-mutations.ts:651

): Promise<void> {
  const candidateRealPath = await realpath(candidatePath)
  const relativeToRoot = relative(rootRealPath, candidateRealPath)
  // Why: `..name` is a valid child path; only `..` and `../...` escape.
  if (
    relativeToRoot !== '' &&
    (relativeToRoot === '..' || relativeToRoot.startsWith(`..${sep}`) || isAbsolute(relativeToRoot))
  ) {
    throw new Error(`Path escaped upload root during staging: '${displayPath}'`)
  }
}

function assertRemoteUploadBudget(
  relativePath: string,
  fileBytes: number,
  totalBytes: number
): void {
  if (fileBytes > REMOTE_IMPORT_MAX_FILE_BYTES) {
    throw new Error(`'${relativePath}' is too large for remote import`)
  }
  if (totalBytes > REMOTE_IMPORT_MAX_TOTAL_BYTES) {
    throw new Error('Remote import is too large')
  }
}

function normalizeRelativeUploadPath(path: string): string {
  return path.replace(/[\\/]+/g, '/').replace(/^\/+/, '')
}

/**
 * Pre-scan a directory tree for symlinks. Returns true if any symlink
 * is found anywhere in the subtree.
 */
async function preScanForSymlinks(dirPath: string): Promise<boolean> {
  const entries = await readdir(dirPath, { withFileTypes: true })
  for (const entry of entries) {
    if (entry.isSymbolicLink()) {

View on GitHub (pinned to 1136503c6a)

Solutions

1. Exclude the large file from the import selection and transfer it separately (e.g., scp directly to the remote host).
2. Split or compress the file so it is under 25 MB before staging.
3. If importing a directory, remove or move the oversized file out of the source tree first.

Example fix

// before: stage a 40MB file for remote import
// after: transfer it directly and exclude from staging
//   scp large.bin remote:/worktree/
//   then import the remaining files without large.bin

const { stat } = await import('node:fs/promises')
const REMOTE_IMPORT_MAX_FILE_BYTES = 25 * 1024 * 1024

async function assertFileUnderRemoteLimit(filePath: string): Promise<void> {
  const s = await stat(filePath)
  if (s.size > REMOTE_IMPORT_MAX_FILE_BYTES) {
    throw new Error(`${filePath} is ${(s.size / 1048576).toFixed(1)}MB, exceeds 25MB remote file limit`)
  }
}

try {
  await stageRemoteImport(sourcePath)
} catch (error) {
  if (error instanceof Error && error.message.includes('too large for remote import')) {
    showUserError(error.message + ' — transfer this file directly via scp.')
    return
  }
  throw error
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Remote import is too large
• File changed during upload staging: '${displayPath}'
• Path escaped upload root during staging: '${displayPath}'
• File too large: ${(stats.size / 1024 / 1024).toFixed(1)}MB e
• File too large: ${(buffer.byteLength / 1024 / 1024).toFixed(

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