paperclipai/paperclip · error

Invalid scope "${rawValue}". Expected a comma-separated list

Error message

Invalid scope "${rawValue}". Expected a comma-separated list of: ${WORKTREE_MERGE_SCOPES.join(", ")}.

What it means

Thrown by parseWorktreeMergeScopes when the supplied --scope value is non-empty but, after lowercasing and trimming, contains zero tokens that match the allowed WORKTREE_MERGE_SCOPES set (currently 'issues' and 'comments'). Empty/undefined input is valid (defaults to both scopes); only malformed non-empty input triggers this.

Source

Thrown at cli/src/commands/worktree-merge-history-lib.ts:332

    if (createdDelta !== 0) return createdDelta;
    return left.id.localeCompare(right.id);
  });
}

export function parseWorktreeMergeScopes(rawValue: string | undefined): WorktreeMergeScope[] {
  if (!rawValue || rawValue.trim().length === 0) {
    return ["issues", "comments"];
  }

  const parsed = rawValue
    .split(",")
    .map((value) => value.trim().toLowerCase())
    .filter((value): value is WorktreeMergeScope =>
      (WORKTREE_MERGE_SCOPES as readonly string[]).includes(value),
    );

  if (parsed.length === 0) {
    throw new Error(
      `Invalid scope "${rawValue}". Expected a comma-separated list of: ${WORKTREE_MERGE_SCOPES.join(", ")}.`,
    );
  }

  return [...new Set(parsed)];
}

export function buildWorktreeMergePlan(input: {
  companyId: string;
  companyName: string;
  issuePrefix: string;
  previewIssueCounterStart: number;
  scopes: WorktreeMergeScope[];
  sourceIssues: IssueRow[];
  targetIssues: IssueRow[];
  sourceComments: CommentRow[];
  targetComments: CommentRow[];
  sourceProjects?: ProjectRow[];

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Use only the allowed tokens, comma-separated: `--scope issues`, `--scope comments`, or `--scope issues,comments`.
2. Omit --scope entirely to accept the default ['issues','comments'].
3. Check spelling: both scope names are plural lowercase.

Example fix

# before
paperclipai worktree merge-history --scope issue,comment
# after
paperclipai worktree merge-history --scope issues,comments

import { WORKTREE_MERGE_SCOPES, type WorktreeMergeScope } from '../commands/worktree-merge-history-lib.js';
function safeScopes(rawValue: string | undefined): WorktreeMergeScope[] {
  if (!rawValue?.trim()) return ['issues', 'comments'];
  const parsed = rawValue.split(',').map((v) => v.trim().toLowerCase()).filter((v): v is WorktreeMergeScope => (WORKTREE_MERGE_SCOPES as readonly string[]).includes(v));
  return parsed.length > 0 ? [...new Set(parsed)] : ['issues', 'comments']; // fallback instead of throw
}
// use safeScopes(opts.scope) to avoid the throw

function isWorktreeMergeScope(v: string): v is WorktreeMergeScope {
  return (WORKTREE_MERGE_SCOPES as readonly string[]).includes(v.trim().toLowerCase());
}

When it happens

Trigger: Calling `paperclipai worktree ... --scope <value>` (or parseWorktreeMergeScopes programmatically) with a value like 'issue', 'comment', 'all', 'tickets', or a typo such as 'isues'. After split/filter against ['issues','comments'] the parsed array is empty.

Common situations: Typing a singular form ('issue' instead of 'issues'). Using a synonym the tool does not recognize ('threads', 'posts'). Misreading docs and passing 'all' or 'everything'. Stray whitespace/punctuation producing zero valid tokens.

Related errors

• --payload must be a JSON object
• ${name} must be a JSON object
• Invalid ${name} JSON: ${err instanceof Error ? err.message :
• --file is required
• Environment variable ${envName} is empty or not set.

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