stablyai/orca · error · Error

Sparse checkout requires at least one repo-relative director

Error message

Sparse checkout requires at least one repo-relative directory.

What it means

Remote worktree create requested a sparse checkout (args.sparseCheckout set) but normalizeSparseDirectories(args.sparseCheckout.directories) returned an empty array. normalizeSparseDirectories trims, rejects absolute paths and '..' segments, strips leading/trailing slashes, and filters out empty strings and '.' — so if every supplied directory is blank, '.', or whitespace, the result is empty and sparse checkout has nothing to materialize.

Source

Thrown at src/main/ipc/worktree-remote.ts:1628

        `Branch "${branchName}" already exists ${lastBranchConflictKind === 'local' ? 'locally' : 'on a remote'}. Pick a different ${branchConflictSubject}.`
      )
    }
    throw new Error(
      `Could not find an available remote worktree path for "${sanitizedName}". Pick a different worktree name.`
    )
  }

  validateWorkspaceLineageParentBeforeCreate(
    store,
    args.parentWorkspace,
    worktreeWorkspaceKey(`${repo.id}::${remotePath}`)
  )

  const sparseDirectories = args.sparseCheckout
    ? normalizeSparseDirectories(args.sparseCheckout.directories)
    : []
  if (args.sparseCheckout && sparseDirectories.length === 0) {
    throw new Error('Sparse checkout requires at least one repo-relative directory.')
  }
  let sparsePresetId: string | undefined
  if (args.sparseCheckout?.presetId) {
    const preset = store
      .getSparsePresets(repo.id)
      .find((entry) => entry.id === args.sparseCheckout?.presetId)
    if (preset?.repoId === repo.id) {
      try {
        const presetDirectories = normalizeSparseDirectories(preset.directories)
        const presetSet = new Set(presetDirectories)
        const directoriesMatch =
          presetDirectories.length === sparseDirectories.length &&
          sparseDirectories.every((entry) => presetSet.has(entry))
        sparsePresetId = directoriesMatch ? preset.id : undefined
      } catch {
        // Why: corrupt preset data should not block creation or falsely label the new worktree.
      }
    }

View on GitHub (pinned to 1136503c6a)

Solutions

1. Supply at least one valid repo-relative directory (e.g. 'src').
2. Validate the sparse directory list is non-empty after normalization before enabling the create button.
3. If using a preset, ensure the preset actually stores directories and isn't blank.

Example fix

// before
const sparseDirectories = args.sparseCheckout
  ? normalizeSparseDirectories(args.sparseCheckout.directories)
  : []
if (args.sparseCheckout && sparseDirectories.length === 0) {
  throw new Error('Sparse checkout requires at least one repo-relative directory.')
}

// after — guard at the caller so the user never reaches the throw
const dirs = normalizeSparseDirectories(args.sparseCheckout?.directories ?? [])
if (args.sparseCheckout && dirs.length === 0) {
  return { ok: false, error: 'Add at least one repo-relative directory to enable sparse checkout.' }
}

import { normalizeSparseDirectories } from './sparse-checkout-directories'
// before create:
if (args.sparseCheckout) {
  const dirs = normalizeSparseDirectories(args.sparseCheckout.directories)
  if (dirs.length === 0) {
    return { ok: false, fieldError: 'sparseDirectories', message: 'Add at least one repo-relative directory.' }
  }
}

function hasSparseDirectories(input: { directories: string[] } | undefined): input is { directories: string[] } {
  return !!input && normalizeSparseDirectories(input.directories).length > 0
}

catch (err) {
  if (err instanceof Error && err.message === 'Sparse checkout requires at least one repo-relative directory.') {
    focusSparseDirectoryField()
  } else { throw err }
}

When it happens

Trigger: args.sparseCheckout is truthy but args.sparseCheckout.directories is [], [''], ['.'], or contains only whitespace/dot entries. Reached at worktree-remote.ts:1628 after the lineage parent validation.

Common situations: UI submitted an empty sparse directory list because the user cleared the field; a preset resolved to no directories; trailing/whitespace-only entries from CSV paste; a default of '.' or '/' filtered away by normalization.

Related errors

• Couldn't verify the SSH connection. Reconnect the host and t
• ${label} is required
• Upload source changed while being inspected: ${sourcePath}
• No SSH connection for "${connectionId}"
• SSH connection is not active — please reconnect and try agai

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