paperclipai/paperclip · error · Error

--version requires an exact published version, received

Error message

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

What it means

Format guard for the --version flag: the installer only accepts an exact published semver string (matched by EXACT_VERSION_PATTERN) so it can pin the npm spec deterministically; ranges, dist-tags, or whitespace-padded values fail this check before any registry call.

Solutions

1. Pass an exact published version (e.g. 2026.101.0) to --version.

When it happens

Trigger: Thrown at cli/src/commands/install.ts:101 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/ba2fcd9196f0fad6. Report an issue: GitHub.

Appendix: source

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

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

export function assertSupportedNodeVersion(): void {
  if (!isSupportedNodeVersion(process.versions.node)) {
    throw new Error(`Installing or updating Paperclip requires Node.js ${MINIMUM_NODE_VERSION} or newer (found ${process.version} at ${process.execPath}). Put a supported Node bin directory first on PATH and run 'npx paperclipai@latest install --yes' to re-pin an existing managed install.`);
  }
}

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 01ad858492)