stablyai/orca · error · WorktreeCopyBudgetFallbackError

APFS clone failed and a real copy of "${target}" would excee

Error message

APFS clone failed and a real copy of "${target}" would exceed the copy budget

What it means

On macOS, Orca attempts an APFS clone (copy-on-write, ~free, bytes never charged to the copy budget) to materialize a worktree-linked path. The clone failed for a reason OTHER than ApfsCloneUnavailableError (e.g. cross-volume, non-APFS disk, transient error). The fallback would be a real byte-for-byte cp, but this entry was admitted as a free clone so its bytes were never budgeted; realCopyFallbackAllowed() re-checks the budget and returns false — charging the bytes now would exceed it. Rather than silently reopen the unbounded copy the budget exists to close, Orca throws WorktreeCopyBudgetFallbackError.

Source

Thrown at src/main/ipc/worktree-symlinks.ts:144

            apfsFilesystemCache
          ))
      await cloneWorktreePath(copySource, target, sourceIsDirectory)
      return
    } catch (error) {
      if (error instanceof WorktreeLinkedPathTargetExistsError) {
        return
      }
      // Why: APFS clone-copy can fail across volumes or on non-APFS disks.
      // Fall back per mode without touching any target path that may have
      // appeared after our preflight.
      if (!(error instanceof ApfsCloneUnavailableError)) {
        console.warn(`[worktree-symlinks] APFS clone-copy unavailable for "${target}":`, error)
        // Why: the fallback is a real byte-for-byte copy. If this entry was
        // admitted as a free clone its bytes were never charged, so bill them
        // now — and refuse if they no longer fit, rather than silently
        // reopening the unbounded copy this budget exists to close.
        if (mode === 'copy' && !realCopyFallbackAllowed()) {
          throw new WorktreeCopyBudgetFallbackError(target)
        }
      }
    }
  }
  if (mode === 'copy') {
    await copyWorktreePath(copySource, target)
    return
  }
  await symlinkWorktreePath(source, target, sourceIsDirectory, options.platform ?? process.platform)
}

/** Whether this copy will land as an APFS clone rather than a byte-for-byte
 *  copy. Only the volume probe can answer it, and that probe writes nothing. */
async function copyIsCopyOnWrite(
  source: string,
  worktreePath: string,
  options: WorktreeLinkedPathOptions,
  apfsFilesystemCache: DarwinFilesystemCache

View on GitHub (pinned to 1136503c6a)

Solutions

Ensure source and target worktree paths are on the same APFS volume so the clone succeeds and no fallback copy is needed.
Raise the worktree copy budget so the real-copy fallback fits.
Reduce what is materialized by copy (use 'share' or 'symlink' mode for large dirs like node_modules) so the failing entry isn't admitted as a copy.
Investigate the underlying clone error (logged via console.warn) — a transient FS error may be retryable.

Example fix

// before
if (mode === 'copy' && !realCopyFallbackAllowed()) {
  throw new WorktreeCopyBudgetFallbackError(target)
}

// after — surface the budget gap with actionable detail
if (mode === 'copy' && !realCopyFallbackAllowed()) {
  throw new WorktreeCopyBudgetFallbackError(target, { neededBytes: estimateEntrySize(copySource), budget: remainingBudget() })
}

Defensive patterns

Strategy: validation

Validate before calling

// Before materializing: estimate the copy cost if clone may fail
const sameVolume = await areOnSameApfsVolume(sourceRoot, worktreePath)
if (mode === 'copy' && process.platform === 'darwin' && !sameVolume) {
  const est = await estimateTreeBytes(copySource)
  if (est > remainingCopyBudget()) {
    return { ok: false, error: 'Copy fallback would exceed budget; use share/symlink mode or same-volume target.' }
  }
}

Type guard

function isWorktreeCopyBudgetFallbackError(err: unknown): boolean {
  return err instanceof Error && err.name === 'WorktreeCopyBudgetFallbackError'
}

Try / catch

catch (err) {
  if (err instanceof Error && err.name === 'WorktreeCopyBudgetFallbackError') {
    // retry with share/symlink mode for the offending large entry, or raise the budget
    await materializeLinkedPath(source, copySource, target, isDir, isSym, 'symlink', options, cache, realCopyFallbackAllowed)
  } else { throw err }
}

Prevention

Keep source and target worktree paths on the same APFS volume so clones succeed.
Use 'share' or 'symlink' mode for large dirs (e.g. node_modules) to avoid copy-budget pressure.
Size the worktree copy budget to the largest expected single entry.
Watch console.warn lines for recurring clone failures that signal a cross-volume setup.

When it happens

Trigger: macOS create where mode === 'copy', the APFS clone threw a non-ApfsCloneUnavailableError, and realCopyFallbackAllowed() (the budget gate) returns false. Reached at worktree-remote.ts-adjacent worktree-symlinks.ts:143-144 inside createWorktreeLinkedPath.

Common situations: node_modules-sized entry cloned across volumes (clone fails, real copy is huge); non-APFS destination disk where clone can't succeed and the directory tree is large; budget configured tightly; many large entries admitted as clones that all fail together (e.g. source and target on different filesystems), exhausting the fallback budget at once.

Related errors

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