stablyai/orca · error

Branch name must not start with "-"

Error message

Branch name must not start with "-"

What it means

Thrown by resolveCreateBranchName for a LOCAL repo when the user-supplied branch name override begins with '-'. A leading hyphen would be parsed by git as an option flag rather than a ref, producing confusing behavior. The check runs before git check-ref-format --branch to give an unambiguous message. This is the local-repo (gitExecFileAsync) variant; the SSH variant is error 1322.

Source

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

    )
  } catch {
    // Best-effort cleanup; keep the sparse setup error as the actionable failure.
  }
}

async function resolveCreateBranchName(
  repoPath: string,
  branchNameOverride: string | undefined,
  sanitizedName: string,
  settings: BranchPrefixSettings,
  username: string | null,
  gitOptions: { wslDistro?: string } = {}
): Promise<string> {
  if (!branchNameOverride) {
    return computeValidatedBranchName(sanitizedName, settings, username)
  }
  if (branchNameOverride.startsWith('-')) {
    throw new Error('Branch name must not start with "-"')
  }
  await gitExecFileAsync(['check-ref-format', '--branch', branchNameOverride], {
    cwd: repoPath,
    ...gitOptions
  })
  return branchNameOverride
}

async function resolveCreateBranchNameSsh(
  provider: SshGitProvider,
  repoPath: string,
  branchNameOverride: string | undefined,
  sanitizedName: string,
  settings: BranchPrefixSettings,
  username: string | null
): Promise<string> {
  if (!branchNameOverride) {
    return computeValidatedBranchName(sanitizedName, settings, username)

View on GitHub (pinned to 1136503c6a)

Solutions

1. Strip or reject a leading '-' in branchNameOverride before calling the create API.
2. Validate the override with git check-ref-format --branch (or the same startsWith('-') guard) in the UI before submit.
3. If the dash is meaningful, rename the branch so the leading character is alphanumeric.

Example fix

// before
if (branchNameOverride.startsWith('-')) {
  throw new Error('Branch name must not start with "-"')
}

// after — reject early at the caller with the user-facing fix
if (branchNameOverride.startsWith('-')) {
  throw new Error('Branch name must not start with "-". Remove the leading dash or prefix it (e.g. "ticket-123").')
}

function isValidBranchOverride(name: string | undefined): boolean {
  return !name || (!name.startsWith('-') && name.trim().length > 0)
}
// before create:
if (!isValidBranchOverride(args.branchNameOverride)) {
  return { ok: false, fieldError: 'branchName', message: 'Branch name must not start with "-".' }
}

function isSafeBranchName(name: string): boolean {
  return name.length > 0 && !name.startsWith('-') && !name.startsWith('.') && !/[^\x21-\x7e]/.test(name) && !name.includes('..')
}

catch (err) {
  if (err instanceof Error && err.message.startsWith('Branch name must not start')) {
    showFieldError('branchName', 'Remove the leading dash from the branch name.')
  } else { throw err }
}

When it happens

Trigger: A worktree create with args.branchNameOverride set to a string starting with '-' (e.g. '-feature', '--foo'), called against a local repo path. Reached at worktree-remote.ts:555 inside resolveCreateBranchName after the !branchNameOverride early return.

Common situations: CLI/UI prefilled a branch name from a ticket id that begins with '-'; a template or paste inserted a leading dash; automated tooling generating branch names from arbitrary input without sanitization.

Related errors

• ${name} must be a positive integer, received ${value}
• no benchmark file exists at both HEAD and HEAD~1 in this che
• No worktrees on environment ${envName}
• No worktrees on environment ${envName}
• Invalid repository name derived from URL

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