{"record":{"id":"ba2fcd9196f0fad6","repo":"paperclipai/paperclip","slug":"version-requires-an-exact-published-version-rec","errorCode":null,"errorMessage":"--version requires an exact published version, received '${options.version}'.","messagePattern":"--version requires an exact published version, received '(.+?)'\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/install.ts","lineNumber":101,"sourceCode":"  return ordered;\n}\n\nfunction assertSupportedNodeVersion(): void {\n  const major = Number(process.versions.node.split(\".\")[0]);\n  if (!Number.isFinite(major) || major < 20) {\n    throw new Error(`Managed installs require Node.js 20 or newer (found ${process.version}).`);\n  }\n}\n\nexport function resolveNpmInstallRequest(options: InstallOptions): {\n  spec: string;\n  channel: InstallChannel;\n} {\n  if (options.canary && options.version) throw new Error(\"Choose either --canary or --version, not both.\");\n  if (options.version) {\n    const version = options.version.trim();\n    if (!EXACT_VERSION_PATTERN.test(version)) {\n      throw new Error(`--version requires an exact published version, received '${options.version}'.`);\n    }\n    return { spec: version, channel: \"pinned\" };\n  }\n  return options.canary ? { spec: \"canary\", channel: \"canary\" } : { spec: \"latest\", channel: \"latest\" };\n}\n\nfunction parseResolvedVersion(stdout: string): string {\n  const trimmed = stdout.trim();\n  if (!trimmed) throw new Error(\"npm returned an empty version response.\");\n  try {\n    const parsed = JSON.parse(trimmed) as unknown;\n    if (typeof parsed === \"string\") return parsed;\n  } catch {\n    if (EXACT_VERSION_PATTERN.test(trimmed)) return trimmed;\n  }\n  throw new Error(`npm returned an unexpected version response: ${trimmed}`);\n}\n","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/install.ts#L83-L119","documentation":"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.","triggerScenarios":"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.","commonSituations":"Assuming --version accepts an npm range, copy-pasting a tag like 'canary', or a typo dropping a version segment.","solutions":["Pass a full exact version: --version 1.2.3.","For prereleases, use the full tag: --version 1.2.3-beta.1.","For a floating/range install, omit --version and use --canary or the default latest channel instead."],"exampleFix":"// before\n--version \"1.x\"\n// after\n--version 1.2.3","handlingStrategy":"validation","validationCode":"const EXACT_VERSION_PATTERN = /^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$/;\nfunction isValidExactVersion(value: string | undefined): boolean {\n  return !!value && EXACT_VERSION_PATTERN.test(value.trim());\n}\n\nif (opts.version && !isValidExactVersion(opts.version)) {\n  console.error(`--version requires an exact published version, received '${opts.version}'.`);\n  process.exit(1);\n}","typeGuard":"function isExactSemver(value: string): boolean {\n  return /^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);\n}","tryCatchPattern":null,"preventionTips":["Pass a full major.minor.patch version.","For prereleases, include the full prerelease tag.","Do not pass npm ranges or tag names like 'latest' to --version."],"tags":["cli","install","argument-validation","semver"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}