paperclipai/paperclip · error · Error

--version requires an exact published version, received '${o

Error message

--version requires an exact published version, received '${options.version}'.

What it means

Thrown by resolveNpmInstallRequest (install.ts:101) when --version is provided but does not match EXACT_VERSION_PATTERN (^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$). The installer needs a concrete published version (optionally with a prerelease tag); ranges, 'latest', carens, or partial versions are rejected.

Source

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

  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;
  }
  throw new Error(`npm returned an unexpected version response: ${trimmed}`);
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass a full exact version: --version 1.2.3.
2. For prereleases, use the full tag: --version 1.2.3-beta.1.
3. For a floating/range install, omit --version and use --canary or the default latest channel instead.

Example fix

// before
--version "1.x"
// after
--version 1.2.3

const EXACT_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
function isValidExactVersion(value: string | undefined): boolean {
  return !!value && EXACT_VERSION_PATTERN.test(value.trim());
}

if (opts.version && !isValidExactVersion(opts.version)) {
  console.error(`--version requires an exact published version, received '${opts.version}'.`);
  process.exit(1);
}

function isExactSemver(value: string): boolean {
  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
}

When it happens

Trigger: Passing --version "1.x", --version ">=1.2", --version "latest", --version "1.2" (missing patch), or --version "1.2.3-beta.1" is allowed (prerelease) but "1.2.3-beta.1+build" (build metadata) is not, since the pattern omits +build.

Common situations: Assuming --version accepts an npm range, copy-pasting a tag like 'canary', or a typo dropping a version segment.

Related errors

• Choose either --canary or --version, not both.
• --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/ba2fcd9196f0fad6. Report an issue: GitHub.