paperclipai/paperclip · error

Worktree name must contain only letters, numbers, dots…

Error message

Worktree name must contain only letters, numbers, dots, underscores, or dashes.

What it means

Character-set guard on the worktree name: the name becomes a filesystem directory and a git branch label, so anything outside letters, numbers, dots, underscores, and dashes is rejected to keep both valid.

Solutions

1. Use only letters, numbers, dots, underscores, or dashes in the worktree name.

When it happens

Trigger: Thrown at cli/src/commands/worktree.ts:270 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/83f60afafb7386fb. Report an issue: GitHub.

Appendix: source

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

    `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 = {
  getObject(companyId: string, objectKey: string): Promise<Buffer>;
  putObject(companyId: string, objectKey: string, body: Buffer, contentType: string): Promise<void>;
};

View on GitHub (pinned to 01ad858492)