stablyai/orca · error

Invalid worktree path

Error message

Invalid worktree path

What it means

Thrown by ensurePathWithinWorkspace when the resolved targetPath escapes the workspaceDir. It computes the relative path from workspaceDir to targetPath and rejects if that relative path is absolute (different drive/root on Windows) or starts with '..'. This is the path-traversal guard preventing a worktree from being created outside the configured workspace directory, which could overwrite arbitrary files or break assumptions about containment.

Source

Thrown at src/main/ipc/worktree-logic.ts:84

    .replace(/[\u202a-\u202e\u2066-\u2069]/g, '')
    .replace(/\s+/g, ' ')
    .trim()
    .slice(0, 120)
    .trim()

  return sanitized || undefined
}

/**
 * Ensure a target path is within the workspace directory (prevent path traversal).
 */
export function ensurePathWithinWorkspace(targetPath: string, workspaceDir: string): string {
  const resolvedWorkspaceDir = resolve(workspaceDir)
  const resolvedTargetPath = resolve(targetPath)
  const rel = relative(resolvedWorkspaceDir, resolvedTargetPath)

  if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) {
    throw new Error('Invalid worktree path')
  }

  return resolvedTargetPath
}

/**
 * Compute the filesystem path where the worktree directory will be created.
 *
 * Why WSL special case: when the repo lives on a WSL filesystem, worktrees
 * must also live on the WSL filesystem. Creating them on the Windows side
 * (/mnt/c/...) would be extremely slow due to cross-filesystem I/O and
 * the terminal would open a Windows shell instead of WSL. We mirror the
 * Windows workspace layout inside ~/orca/workspaces on the WSL filesystem
 * (e.g. \\wsl.localhost\Ubuntu\home\user\orca\workspaces\repo\feature).
 */
export function computeWorktreePath(
  sanitizedName: string,
  repoPath: string,

View on GitHub (pinned to 1136503c6a)

Solutions

1. Ensure targetPath is constructed as a child of workspaceDir (e.g. path.join(workspaceDir, name)).
2. Verify the workspaceDir setting points to the intended parent and is on the same drive/root.
3. If the user can specify a custom location, validate it resolves inside workspaceDir before calling ensure, and show a clear error.

Example fix

// before
ensurePathWithinWorkspace('/etc/evil', '/home/user/orca/workspaces')
// after
ensurePathWithinWorkspace('/home/user/orca/workspaces/repo/feature', '/home/user/orca/workspaces')

import { resolve, relative, isAbsolute, sep } from 'node:path'
function isPathInsideWorkspace(targetPath: string, workspaceDir: string): boolean {
  const rel = relative(resolve(workspaceDir), resolve(targetPath))
  return !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`)
}

try {
  ensurePathWithinWorkspace(targetPath, workspaceDir)
} catch (e) {
  if (/Invalid worktree path/.test((e as Error).message)) {
    showFieldError('path', 'Path must be inside the workspace directory.')
    return
  } else throw e
}

When it happens

Trigger: ensurePathWithinWorkspace(targetPath, workspaceDir) where targetPath resolves outside workspaceDir — e.g. '../sibling', an absolute path elsewhere, or a Windows path on a different drive than the workspace. The relative() result is absolute or begins with '..'.

Common situations: User-supplied or computed worktree path points outside the workspace root. Different drive letters on Windows (C: workspace vs D: target) make relative() return an absolute path. Symlink resolution moves the target outside. Misconfigured workspaceDir setting.

Related errors

• Invalid renderer output path: ${String(outputPath)}
• Clone path must be inside the destination directory
• Access denied: invalid submodule path
• Access denied: submodule path escapes the selected worktree
• Path "${filePath}" resolves outside the worktree

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