stablyai/orca · error · Error

Remote import is too large

Error message

Remote import is too large

What it means

Thrown by assertRemoteUploadBudget when the cumulative byte total across all staged files exceeds REMOTE_IMPORT_MAX_TOTAL_BYTES (100 MB). This cap prevents the combined base64 payload of a directory import from overwhelming the IPC channel or remote relay.

Source

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

  // 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()) {
      return true
    }
    if (entry.isDirectory()) {

View on GitHub (pinned to 1136503c6a)

Solutions

1. Reduce the import scope: exclude large subdirectories (node_modules, build output, media).
2. Split the import into multiple smaller batches, each under 100 MB total.
3. Transfer large directories directly to the remote host via scp/rsync instead of through the IPC staging path.

Example fix

// before: import entire project including 80MB of assets
// after: exclude assets, import separately
//   import /project/src and /project/docs (under 100MB)
//   scp -r /project/assets remote:/worktree/assets

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

async function assertTreeUnderTotalLimit(rootPath: string): Promise<void> {
  const { readdir, lstat } = await import('node:fs/promises')
  let total = 0
  async function visit(dir: string): Promise<void> {
    for (const e of await readdir(dir, { withFileTypes: true })) {
      const p = join(dir, e.name)
      if (e.isDirectory()) { await visit(p); continue }
      total += (await lstat(p)).size
      if (total > REMOTE_IMPORT_MAX_TOTAL_BYTES) {
        throw new Error(`Total exceeds 100MB remote import limit at ${p}`)
      }
    }
  }
  await visit(rootPath)
}

try {
  await stageRemoteImport(sourcePath)
} catch (error) {
  if (error instanceof Error && error.message === 'Remote import is too large') {
    showUserError('Total import exceeds 100MB. Reduce scope or use scp for bulk transfer.')
    return
  }
  throw error
}

When it happens

Trigger: Importing a directory tree whose total file sizes sum to more than 100 MB. The running total (totalBytesBefore + current file size) is checked per file, so the error fires on the file that pushes the total over the limit.

Common situations: Bulk-importing a large project directory with many source files, assets, or node_modules. Importing a directory with large media or data files that individually pass the 25 MB file cap but collectively exceed 100 MB.

Related errors

• '${relativePath}' is too large for remote import
• 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/e1c01ab935273a2f. Report an issue: GitHub.