Worktree name must contain only letters, numbers, dots, unde

Error message

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

What it means

Thrown by resolveWorktreeMakeName when the trimmed name is non-empty but fails the regex ^[A-Za-z0-9._-]+$. The name becomes a filesystem branch/directory identifier (prefixed with 'paperclip-'), so characters that break git branches or paths — spaces, slashes, colons, shell metacharacters, Unicode — are rejected.

Source

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

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

View on GitHub (pinned to 67001ec6eb)

Solutions

Use only letters, numbers, dots, underscores, and dashes: `paperclipai worktree make my-feature`.
Replace spaces with dashes or underscores and strip slashes: 'feat/xyz' -> 'feat-xyz'.
Avoid slashes — this name is a single path/branch segment, not a nested path.

Example fix

# before
paperclipai worktree make "feature/xyz branch"
# after
paperclipai worktree make feature-xyz-branch

Defensive patterns

Strategy: validation

Validate before calling

function sanitizeWorktreeName(raw: string): string | null {
  const trimmed = raw.trim();
  if (!trimmed) return null;
  return /^[A-Za-z0-9._-]+$/.test(trimmed) ? trimmed : trimmed.replace(/[^A-Za-z0-9._-]/g, '-');
}
// const safe = sanitizeWorktreeName(raw) ?? throwOnEmpty;  // pass safe to resolveWorktreeMakeName

Type guard

function isValidWorktreeName(name: string): boolean {
  return /^[A-Za-z0-9._-]+$/.test(name.trim());
}

Prevention

Derive worktree names from slugs (branch, ticket id) rather than free-form titles.
Replace disallowed characters with dashes before validation.
Avoid slashes — worktree names are single branch/path segments.

When it happens

Trigger: Passing a worktree name containing a space, slash, colon, @, parentheses, emoji, or any non-[A-Za-z0-9._-] character to the make/create flow. E.g. `paperclipai worktree make 'my feature'`, `'feature/xyz'`, `'feat@v2'`.

Common situations: Using a descriptive ticket title as the worktree name (contains spaces/slashes). Copy-pasting a branch name with slashes expecting it to work. Non-ASCII characters in the name.

Related errors

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