paperclipai/paperclip · error · Error

Invalid branch name "${branchName}": ${extractExecSyncErrorM

Error message

Invalid branch name "${branchName}": ${extractExecSyncErrorMessage(error) ?? String(error)}

What it means

Thrown by validateGitBranchName when `git check-ref-format --branch <value>` exits non-zero, meaning git itself rejected the proposed branch name as malformed or reserved. The error message embeds git's stderr so the exact rule violation is visible.

Source

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

    }).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 {
  const workspace = detectGitWorkspaceInfo(cwd);
  if (!workspace) {
    throw new Error("Current directory is not inside a git repository.");
  }
  if (workspace.gitDir === workspace.commonDir) {
    return workspace.root;
  }
  return path.resolve(workspace.commonDir, "..");

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Sanitize the proposed branch name (replace [^A-Za-z0-9._-] with '-') before validation.
2. Pick a branch name manually that obeys git ref-format rules.
3. Use resolveRepairWorktreeDirName's normalization logic on the input before validation if a safe slug is acceptable.
4. Read the embedded git error text to identify the specific forbidden character/pattern and remove it.

Example fix

// before
const branch = issueTitle; // "fix: handle ~ special chars"
// after
const branch = issueTitle.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');

function sanitizeBranchName(raw: string): string {
  return raw.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').replace(/\.lock$/i, '-lock');
}

function isValidGitBranch(name: string): boolean {
  try {
    execFileSync('git', ['check-ref-format', '--branch', name], { stdio: 'ignore' });
    return true;
  } catch { return false; }
}

try {
  validateGitBranchName(repoRoot, branch);
} catch (e) {
  if (/Invalid branch name/.test((e as Error).message)) branch = sanitizeBranchName(branch);
  else throw e;
}

When it happens

Trigger: Passing a branch name that violates git ref-format rules: contains '..' or ' ', has a trailing .lock/.dot, uses control characters, starts with '-' or '.', contains '~', '^', ':', '?', '*', '[', '\', or equals '@{'; or a name like 'HEAD' that is reserved.

Common situations: Auto-derived branch names from issue titles or file paths containing forbidden characters; copy-paste introducing spaces or special chars; names ending in '.lock' colliding with lockfile refs; very long names exceeding git limits.

Related errors

• Branch name is required.
• 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/49e00664f3996d6b. Report an issue: GitHub.