{"record":{"id":"6332b1b4a2b607e9","repo":"docmirror/dev-sidecar","slug":"invalid-version-string-version","errorCode":null,"errorMessage":"Invalid version string: ${version}","messagePattern":"Invalid version string: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/core/src/utils/util.version.js","lineNumber":4,"sourceCode":"function parseVersion (version) {\n  const matched = version.match(/^v?(\\d{1,2}(?:\\.\\d{1,2})*)[.-]?(.*)$/)\n  if (!matched) {\n    throw new Error(`Invalid version string: ${version}`)\n  }\n  const versionInfo = {\n    versions: matched[1].split('.'), // 版本号数组\n    pre: matched[2], // 预发布版本号\n  }\n\n  // 将 versions 中的数字字符串转为数字\n  for (let i = 0; i < versionInfo.versions.length; i++) {\n    versionInfo.versions[i] = Number.parseInt(versionInfo.versions[i])\n  }\n\n  return versionInfo\n}\n\n/**\n * 比较版本号\n *\n * @param onlineVersion  线上版本号","sourceCodeStart":1,"sourceCodeEnd":22,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/core/src/utils/util.version.js#L1-L22","documentation":"parseVersion() parses a version string like 'v1.2.3' or '1.2.3-beta.1' into numeric parts plus a prerelease suffix using a strict regex (^v?digits(\\.digits)*[.-]suffix$). If the string does not match — wrong characters, too many dots, empty, or non-version text — this error is thrown. It is thrown inside isNewVersion's try/catch, which converts it to result -999 with a logged error.","triggerScenarios":"Calling the module's parseVersion (or indirectly isNewVersion) with strings like 'abc', '', '1.2.3.4.5.6...x', 'version 1.2', or a URL/text response mistakenly used as the version; comparing when onlineVersion fetch returned HTML/an error page instead of a version string.","commonSituations":"Update check against a remote endpoint that returned an error body instead of a version; local package version read from an unexpected source (e.g. malformed package.json); manual version strings with 'v' plus extra text like 'v1.2.3 (build 45)'; empty version variables.","solutions":["Validate the version string matches /^v?\\d+(\\.\\d+)*([.-].+)?$/ before parsing","Sanitize what you feed isNewVersion: trim and strip prefixes like 'version ' or build annotations","If using isNewVersion for update checks, handle its -999 return (comparison failed) rather than letting parseVersion throw","Fix the source of the version data (e.g. ensure the remote version endpoint returns a bare semver string)"],"exampleFix":"// before\nconst isNew = version.isNewVersion(fetchVersionBody, '1.2.0') // body may be HTML -> parseVersion throws\n// after\nfunction isValidVersion (v) { return typeof v === 'string' && /^v?\\d{1,2}(\\.\\d{1,2})*([.-].+)?$/.test(v.trim()) }\nconst isNew = isValidVersion(fetchVersionBody) ? version.isNewVersion(fetchVersionBody.trim(), '1.2.0') : -999","handlingStrategy":"validation","validationCode":"function isValidVersionString(v) {\n  return typeof v === 'string' && /^v?\\d{1,2}(?:\\.\\d{1,2})*[.-]?[^\\s]*$/.test(v.trim())\n}\n// use only when isValidVersionString(remoteVersion) is true","typeGuard":"function isVersionString(v) { return typeof v === 'string' && /^v?\\d{1,2}(?:\\.\\d{1,2})*([.-].+)?$/.test(v.trim()) }","tryCatchPattern":"try {\n  const result = version.isNewVersion(online, current)\n} catch (e) {\n  if (String(e.message).startsWith('Invalid version string')) {\n    log.error(`Unparseable version: ${e.message}`)\n    return -999 // treat as 'unknown comparison'\n  }\n  throw e\n}","preventionTips":["Trim and sanitize remote version responses before comparing","Handle isNewVersion's -999 sentinel as a failed comparison","Ensure version sources return bare semver strings (no HTML/error pages)","Add a regex pre-check in any code path that feeds dynamic strings to version parsing"],"tags":["versioning","parsing","input-validation"],"backgroundTag":"invalid-version-string","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}