paperclipai/paperclip · error

Worktree name is required.

Error message

Worktree name is required.

What it means

Required-argument guard in the worktree:make name resolver: the positional name argument (and any fallback) resolved to an empty string, so there is no directory/branch name to build the worktree from.

Solutions

1. Provide a worktree name argument.

When it happens

Trigger: Thrown at cli/src/commands/worktree.ts:267 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

): 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}`,
    `stopped project workspace runtimes: ${summary.stoppedProjectWorkspaceRuntimes}`,
    `stopped execution workspace runtimes: ${summary.stoppedExecutionWorkspaceRuntimes}`,
    `stopped runtime services: ${summary.stoppedRuntimeServices}`,
  ].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 01ad858492)