paperclipai/paperclip · error · Error

Choose either --canary or --version, not both.

Error message

Choose either --canary or --version, not both.

What it means

Thrown by resolveNpmInstallRequest (install.ts:97) when both --canary and --version are set. The two flags select mutually exclusive install channels (canary tag vs a pinned exact version), so specifying both is ambiguous and rejected up front.

Source

Thrown at cli/src/commands/install.ts:97

    ordered.push(entry);
  };

  visit("@paperclipai/server");
  return ordered;
}

function assertSupportedNodeVersion(): void {
  const major = Number(process.versions.node.split(".")[0]);
  if (!Number.isFinite(major) || major < 20) {
    throw new Error(`Managed installs require Node.js 20 or newer (found ${process.version}).`);
  }
}

export function resolveNpmInstallRequest(options: InstallOptions): {
  spec: string;
  channel: InstallChannel;
} {
  if (options.canary && options.version) throw new Error("Choose either --canary or --version, not both.");
  if (options.version) {
    const version = options.version.trim();
    if (!EXACT_VERSION_PATTERN.test(version)) {
      throw new Error(`--version requires an exact published version, received '${options.version}'.`);
    }
    return { spec: version, channel: "pinned" };
  }
  return options.canary ? { spec: "canary", channel: "canary" } : { spec: "latest", channel: "latest" };
}

function parseResolvedVersion(stdout: string): string {
  const trimmed = stdout.trim();
  if (!trimmed) throw new Error("npm returned an empty version response.");
  try {
    const parsed = JSON.parse(trimmed) as unknown;
    if (typeof parsed === "string") return parsed;
  } catch {
    if (EXACT_VERSION_PATTERN.test(trimmed)) return trimmed;

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pick one channel: either --canary OR --version <exact>.
2. In scripts, set only one of the two based on intent.
3. For reproducible installs, prefer --version with a pinned semver.

Example fix

// before
paperclipai install --canary --version 1.2.3
// after
paperclipai install --version 1.2.3

function resolveChannel(opts: InstallOptions): 'canary' | 'pinned' | 'latest' {
  if (opts.canary && opts.version) {
    throw new Error('Pass either --canary or --version, not both.');
  }
  if (opts.version) return 'pinned';
  return opts.canary ? 'canary' : 'latest';
}

function isMutuallyExclusiveFlags(opts: InstallOptions): boolean {
  return !(opts.canary && opts.version);
}

When it happens

Trigger: Running `paperclipai install --canary --version 1.2.3`. The guard fires immediately, before any version normalization or network call.

Common situations: Copy-pasting a command that accumulated both flags, or a wrapper script that always sets --canary and forwards a user-provided --version.

Related errors

• --version requires an exact published version, received '${o
• --version is only supported for npm package installs, not lo
• Approval request failed.
• Invalid --secret-value "${raw}". Use key=value.
• Invalid --adapter-override "${raw}". Use slug=type.

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