{"record":{"id":"f0fb4fd61168e7af","repo":"heygen-com/hyperframes","slug":"registry-item-item-name-requires-hyperframes","errorCode":null,"errorMessage":"Registry item \"${item.name}\" requires hyperframes >= ${minCliVersion} (current: ${currentCliVersion}). Run `npx hyperframes@latest add ${item.name}` or upgrade your installed hyperframes CLI.","messagePattern":"Registry item \"(.+?)\" requires hyperframes >= (.+?) \\(current: (.+?)\\)\\. Run `npx hyperframes@latest add (.+?)` or upgrade your installed hyperframes CLI\\.","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 (surfaced as RegistryCompatibilityError) when the installed CLI version is strictly less than an item's valid minCliVersion. compareVersions(current, min) returns negative, so the function returns an error telling the user to upgrade, including the exact `npx hyperframes@latest add <name>` command. The DEV_VERSION skips this gate.","triggerScenarios":"gateRegistryItemsCompatibility runs during add / template fetch / Studio 'add block'; an item declares minCliVersion higher than the running VERSION and checkRegistryItemCompatibility returns the error, re-thrown at compatibility.ts:73.","commonSituations":"An older CLI trying to install a newer registry item that depends on recent features; a pinned global CLI behind the registry; CI pinned to an old version while the registry advanced.","solutions":["Upgrade and retry with the command in the message: `npx hyperframes@latest add <item.name>`","Update your global CLI: `npm i -g hyperframes@latest`","Pin your project scripts to hyperframes@latest so npx always fetches the newest","Develop against the dev build (0.0.0-dev) to bypass the gate locally"],"exampleFix":"// before\nnpx hyperframes@0.6.79 add fancy-block   # block needs >=0.6.80\n// after\nnpx hyperframes@latest add fancy-block","handlingStrategy":"validation","validationCode":"import { compareVersions } from \"compare-versions\";\nfunction cliSatisfies(current: string, min: string | undefined): boolean {\n  if (!min || current === \"0.0.0-dev\") return true;\n  return compareVersions(current, min) >= 0;\n}","typeGuard":null,"tryCatchPattern":"try {\n  gateRegistryItemsCompatibility(items, currentVersion);\n} catch (e) {\n  if (e instanceof RegistryCompatibilityError && e.message.includes(\"requires hyperframes >=\")) {\n    // re-run via `npx hyperframes@latest add <name>` and abort\n  }\n  throw e;\n}","preventionTips":["Pin project scripts to hyperframes@latest so npx fetches the newest","Upgrade the global CLI when the registry advances","Gate installs on cliSatisfies before presenting items to users"],"tags":["registry","compatibility","version","upgrade"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}