paperclipai/paperclip · error · Error

Branch name is required.

Error message

Branch name is required.

What it means

Thrown by validateGitBranchName when nonEmpty(branchName) returns falsy, i.e. the branch name argument is empty, whitespace-only, or null/undefined. The validator needs a non-empty branch before it can run git check-ref-format.

Source

Thrown at cli/src/commands/worktree.ts:628

}

function detectGitBranchName(cwd: string): string | null {
  try {
    const value = execFileSync("git", ["branch", "--show-current"], {
      cwd,
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
    }).trim();
    return nonEmpty(value);
  } catch {
    return null;
  }
}

function validateGitBranchName(cwd: string, branchName: string): string {
  const value = nonEmpty(branchName);
  if (!value) {
    throw new Error("Branch name is required.");
  }
  try {
    execFileSync("git", ["check-ref-format", "--branch", value], {
      cwd,
      stdio: ["ignore", "pipe", "pipe"],
    });
  } catch (error) {
    throw new Error(`Invalid branch name "${branchName}": ${extractExecSyncErrorMessage(error) ?? String(error)}`);
  }
  return value;
}

function isPrimaryGitWorktree(cwd: string): boolean {
  const workspace = detectGitWorkspaceInfo(cwd);
  return Boolean(workspace && workspace.gitDir === workspace.commonDir);
}

function resolvePrimaryGitRepoRoot(cwd: string): string {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Provide an explicit non-empty branch name via the selector or --branch flag.
2. If in detached HEAD, check out or name a branch first before running the worktree command.
3. Validate input.selector with nonEmpty before calling the resolver and surface a clearer CLI error.
4. Detect detached HEAD upstream and require the user to specify a branch explicitly.

Example fix

// before
const branch = detectGitBranchName(cwd) ?? '';
validateGitBranchName(repoRoot, branch);
// after
const branch = nonEmpty(detectGitBranchName(cwd));
if (!branch) throw new Error('Detached HEAD: pass --branch explicitly.');
validateGitBranchName(repoRoot, branch);

function requireBranchName(raw: string | null | undefined): string {
  const v = nonEmpty(raw);
  if (!v) throw new Error('Branch name required (detached HEAD? pass --branch).');
  return v;
}

function isNonEmptyBranchName(name: unknown): name is string {
  return typeof name === 'string' && name.trim().length > 0;
}

When it happens

Trigger: Calling a worktree repair/resolve flow with input.selector that is empty or all whitespace; the selector came from detectGitBranchName returning null in a detached-HEAD state and was passed through unguarded; CLI flag --branch supplied as empty string.

Common situations: Detached HEAD where git branch --show-current returns nothing; a selector/flag that defaulted to empty; whitespace-only input from a templated command; programmatic call passing undefined.

Related errors

• Invalid branch name "${branchName}": ${extractExecSyncErrorM
• Target path already exists: ${targetPath}
• Could not resolve worktree "${selector}". Use a path, a list
• Resolved worktree "${selector}" does not look like a Papercl
• Worktree name is required.

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/313c87b65490cd46. Report an issue: GitHub.