{"record":{"id":"54e3b1852861ea65","repo":"stablyai/orca","slug":"apfs-clone-failed-and-a-real-copy-of-target-w","errorCode":null,"errorMessage":"APFS clone failed and a real copy of \"${target}\" would exceed the copy budget","messagePattern":"APFS clone failed and a real copy of \"(.+?)\" would exceed the copy budget","errorType":"exception","errorClass":"WorktreeCopyBudgetFallbackError","httpStatus":null,"severity":"error","filePath":"src/main/ipc/worktree-symlinks.ts","lineNumber":144,"sourceCode":"            apfsFilesystemCache\n          ))\n      await cloneWorktreePath(copySource, target, sourceIsDirectory)\n      return\n    } catch (error) {\n      if (error instanceof WorktreeLinkedPathTargetExistsError) {\n        return\n      }\n      // Why: APFS clone-copy can fail across volumes or on non-APFS disks.\n      // Fall back per mode without touching any target path that may have\n      // appeared after our preflight.\n      if (!(error instanceof ApfsCloneUnavailableError)) {\n        console.warn(`[worktree-symlinks] APFS clone-copy unavailable for \"${target}\":`, error)\n        // Why: the fallback is a real byte-for-byte copy. If this entry was\n        // admitted as a free clone its bytes were never charged, so bill them\n        // now — and refuse if they no longer fit, rather than silently\n        // reopening the unbounded copy this budget exists to close.\n        if (mode === 'copy' && !realCopyFallbackAllowed()) {\n          throw new WorktreeCopyBudgetFallbackError(target)\n        }\n      }\n    }\n  }\n  if (mode === 'copy') {\n    await copyWorktreePath(copySource, target)\n    return\n  }\n  await symlinkWorktreePath(source, target, sourceIsDirectory, options.platform ?? process.platform)\n}\n\n/** Whether this copy will land as an APFS clone rather than a byte-for-byte\n *  copy. Only the volume probe can answer it, and that probe writes nothing. */\nasync function copyIsCopyOnWrite(\n  source: string,\n  worktreePath: string,\n  options: WorktreeLinkedPathOptions,\n  apfsFilesystemCache: DarwinFilesystemCache","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/ipc/worktree-symlinks.ts#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nif (mode === 'copy' && !realCopyFallbackAllowed()) {\n  throw new WorktreeCopyBudgetFallbackError(target)\n}\n\n// after — surface the budget gap with actionable detail\nif (mode === 'copy' && !realCopyFallbackAllowed()) {\n  throw new WorktreeCopyBudgetFallbackError(target, { neededBytes: estimateEntrySize(copySource), budget: remainingBudget() })\n}","handlingStrategy":"validation","validationCode":"// Before materializing: estimate the copy cost if clone may fail\nconst sameVolume = await areOnSameApfsVolume(sourceRoot, worktreePath)\nif (mode === 'copy' && process.platform === 'darwin' && !sameVolume) {\n  const est = await estimateTreeBytes(copySource)\n  if (est > remainingCopyBudget()) {\n    return { ok: false, error: 'Copy fallback would exceed budget; use share/symlink mode or same-volume target.' }\n  }\n}","typeGuard":"function isWorktreeCopyBudgetFallbackError(err: unknown): boolean {\n  return err instanceof Error && err.name === 'WorktreeCopyBudgetFallbackError'\n}","tryCatchPattern":"catch (err) {\n  if (err instanceof Error && err.name === 'WorktreeCopyBudgetFallbackError') {\n    // retry with share/symlink mode for the offending large entry, or raise the budget\n    await materializeLinkedPath(source, copySource, target, isDir, isSym, 'symlink', options, cache, realCopyFallbackAllowed)\n  } else { throw err }\n}","preventionTips":["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."],"tags":["worktree-create","apfs","clone","macos","copy-budget"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}