paperclipai/paperclip · error

Worktree name is required.

Error message

Worktree name is required.

What it means

Thrown by resolveWorktreeMakeName when the provided worktree name is empty or only whitespace after trimming (nonEmpty returns null). A worktree requires a name because it becomes the branch/directory identifier (prefixed with 'paperclip-'). This is the required-field guard that runs before the character-set validation.

Source

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

function formatSeededWorktreeExecutionQuarantineSummary(
  summary: SeededWorktreeExecutionQuarantineSummary,
): string {
  return [
    `disabled timer heartbeats: ${summary.disabledTimerHeartbeats}`,
    `reset running agents: ${summary.resetRunningAgents}`,
    `quarantined in-progress issues: ${summary.quarantinedInProgressIssues}`,
    `unassigned todo issues: ${summary.unassignedTodoIssues}`,
    `unassigned review issues: ${summary.unassignedReviewIssues}`,
  ].join(", ");
}

const WORKTREE_NAME_PREFIX = "paperclip-";

function resolveWorktreeMakeName(name: string): string {
  const value = nonEmpty(name);
  if (!value) {
    throw new Error("Worktree name is required.");
  }
  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
    throw new Error(
      "Worktree name must contain only letters, numbers, dots, underscores, or dashes.",
    );
  }
  return value.startsWith(WORKTREE_NAME_PREFIX) ? value : `${WORKTREE_NAME_PREFIX}${value}`;
}

function resolveWorktreeHome(explicit?: string): string {
  return explicit ?? process.env.PAPERCLIP_WORKTREES_DIR ?? DEFAULT_WORKTREE_HOME;
}

function resolveWorktreeStartPoint(explicit?: string): string | undefined {
  return explicit ?? nonEmpty(process.env.PAPERCLIP_WORKTREE_START_POINT) ?? undefined;
}

type ConfiguredStorage = {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Provide a non-empty name: `paperclipai worktree make my-feature`.
2. If the name comes from a variable, default it: `--name "${NAME:-default}"`.
3. Validate the name is non-empty in your wrapper script before invoking the CLI.

Example fix

# before
paperclipai worktree make ""
# after
paperclipai worktree make my-feature

function requireWorktreeName(name: string): string {
  const trimmed = name.trim();
  if (!trimmed) throw new Error('Worktree name is required.');
  return trimmed;
}
// const name = requireWorktreeName(input);  // gates before resolveWorktreeMakeName

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

When it happens

Trigger: Invoking the worktree make/create flow with an empty --name flag, an all-whitespace name, or programmatically calling resolveWorktreeMakeName('') / resolveWorktreeMakeName(' '). nonEmpty trims and returns null when length is 0.

Common situations: Shell quoting bug dropping the argument (`paperclipai worktree make ""`). Scripted call with an unset variable. UI/CLI form submitted without entering a name.

Related errors

• Worktree name must contain only letters, numbers, dots, unde
• Branch name is required.
• Invalid branch name "${branchName}": ${extractExecSyncErrorM
• Use either --from <worktree> or --from-config/--from-data-di
• Source and target Paperclip configs are the same. Pass --fro

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