{"record":{"id":"fc76672cbeb14ada","repo":"heygen-com/hyperframes","slug":"registry-item-item-name-declares-invalid-minc","errorCode":null,"errorMessage":"Registry item \"${item.name}\" declares invalid minCliVersion \"${minCliVersion}\".","messagePattern":"Registry item \"(.+?)\" declares invalid minCliVersion \"(.+?)\"\\.","errorType":"exception","errorClass":"RegistryCompatibilityError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/registry/compatibility.ts","lineNumber":73,"sourceCode":" * Compatibility-gate a set of resolved items (e.g. an item plus its transitive\n * `registryDependencies`) before any of them are installed. Throws a\n * `RegistryCompatibilityError` on the first item that requires a newer CLI, so\n * a partial install never happens; returns the accumulated (non-fatal)\n * deprecation warnings from every item.\n *\n * Every install path — `add`, template fetch, and the Studio \"add block\"\n * action — funnels through this so a dependency that ships `minCliVersion` is\n * rejected uniformly, not just by `hyperframes add`.\n */\nexport function gateRegistryItemsCompatibility(\n  items: RegistryItem[],\n  currentCliVersion = VERSION,\n): string[] {\n  const warnings: string[] = [];\n  for (const item of items) {\n    const result = checkRegistryItemCompatibility(item, currentCliVersion);\n    if (result.error) {\n      throw new RegistryCompatibilityError(result.error);\n    }\n    warnings.push(...result.warnings);\n  }\n  return warnings;\n}\n","sourceCodeStart":55,"sourceCodeEnd":79,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/registry/compatibility.ts#L55-L79","documentation":"Produced by checkRegistryItemCompatibility (and surfaced as RegistryCompatibilityError by gateRegistryItemsCompatibility) when a registry item's minCliVersion fails to parse. compareVersions throws on non-semver input; the catch block turns that into a clear 'declares invalid minCliVersion' error naming the item and the bad value. The check is skipped entirely for the DEV_VERSION (0.0.0-dev).","triggerScenarios":"A RegistryItem ships item.minCliVersion with a non-semver value (e.g. 'next', 'latest', 'v1'). gateRegistryItemsCompatibility loops items, checkRegistryItemCompatibility's compareVersions throws, and the error is re-thrown as RegistryCompatibilityError.","commonSituations":"A third-party/forked registry item with a typo'd minCliVersion; a dist-tag used where a semver was expected; hand-edited registry JSON; an item authored against a different versioning scheme.","solutions":["Fix the item's minCliVersion to a valid semver (e.g. '0.6.80') in its registry metadata","Remove minCliVersion from the item to skip the gate entirely","If you don't control the item, report it to the registry maintainer","Develop against the dev CLI (0.0.0-dev) which bypasses the check"],"exampleFix":"// before\n{ \"name\": \"my-block\", \"minCliVersion\": \"next\" }\n// after\n{ \"name\": \"my-block\", \"minCliVersion\": \"0.6.80\" }","handlingStrategy":"validation","validationCode":"import { validate } from \"compare-versions\";\nfunction validMinCliVersion(v: string | undefined): boolean {\n  if (!v) return true;\n  try { validate(v); return true; } catch { return false; }\n}","typeGuard":"import { validate } from \"compare-versions\";\nfunction isValidSemver(v: unknown): v is string {\n  return typeof v === \"string\" && (() => { try { validate(v); return true; } catch { return false; } })();\n}","tryCatchPattern":"try {\n  gateRegistryItemsCompatibility(items);\n} catch (e) {\n  if (e instanceof RegistryCompatibilityError && e.message.includes(\"declares invalid minCliVersion\")) {\n    // strip/fix minCliVersion in the offending item, then retry\n  }\n  throw e;\n}","preventionTips":["Author minCliVersion as strict semver (MAJOR.MINOR.PATCH)","Validate registry items against registry-item.json before publishing","Omit minCliVersion rather than guessing a non-semver value"],"tags":["registry","compatibility","semver","metadata"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}