{"record":{"id":"fe06c8f360cafd65","repo":"heygen-com/hyperframes","slug":"incompatible-cli","errorCode":"incompatible-cli","errorMessage":"${err.message}","messagePattern":"\\$\\{err\\.message\\}","errorType":"validation","errorClass":"AddError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/add.ts","lineNumber":170,"sourceCode":"      | \"wrong-type\"\n      | \"install-failed\"\n      | \"example-type\"\n      | \"incompatible-cli\",\n  ) {\n    super(message);\n    this.name = \"AddError\";\n  }\n}\n\n// Compatibility-gate a set of resolved items before any install runs, mapping\n// the shared gate's error into an AddError so the command surfaces the right\n// exit code. Returns the accumulated (non-fatal) warnings from every item.\nfunction assertCompatibleOrThrow(items: RegistryItem[], cliVersion?: string): string[] {\n  try {\n    return gateRegistryItemsCompatibility(items, cliVersion);\n  } catch (err) {\n    if (err instanceof RegistryCompatibilityError) {\n      throw new AddError(err.message, \"incompatible-cli\");\n    }\n    throw err;\n  }\n}\n\n// Install a topologically-ordered plan (dependencies first, requested item\n// last). The installer validates every target before any write; a failure on\n// any item surfaces as an install-failed AddError. Returns all written paths.\nasync function installAll(\n  installPlan: RegistryItem[],\n  destDir: string,\n  baseUrl: string | undefined,\n  force: boolean,\n): Promise<{ written: string[]; preserved: string[] }> {\n  const written: string[] = [];\n  const preserved: string[] = [];\n  try {\n    for (const planItem of installPlan) {","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/add.ts#L152-L188","documentation":"AddError with code 'incompatible-cli', thrown by assertCompatibleOrThrow when the shared compatibility gate (gateRegistryItemsCompatibility) raises a RegistryCompatibilityError. The gate is run over the full resolved item set (the requested item plus its transitive dependencies) before any install writes happen, so a version mismatch fails fast without leaving the tree half-modified.","triggerScenarios":"A registry item declares a minimum (or maximum) CLI version that the running CLI does not satisfy; a dependency requires a feature added after the installed CLI; the catalog page was generated for a newer release than the user's CLI.","commonSituations":"Running an older bundled CLI against newly published registry items; pinning the CLI in CI and forgetting to bump it when adopting a new block; a block that was published against a breaking core change.","solutions":["Upgrade the CLI to the version the gate names: `npm i -g hyperframes@latest` (or the specific version).","If you cannot upgrade, pin an older version of the block/component that is compatible with your CLI.","Check the item's registry-item.json for the declared version range and confirm against `hyperframes --version`."],"exampleFix":"# before: old CLI, new block\n$ hyperframes --version\n0.3.1\n$ hyperframes add new-block   # incompatible-cli\n\n# after: align versions\n$ npm i -g hyperframes@latest\n$ hyperframes add new-block","handlingStrategy":"validation","validationCode":"// Pre-check CLI version against the item's declared range before installing\nimport { satisfies } from 'semver';\nfunction assertCliCompatible(item: RegistryItem, cliVersion: string) {\n  if (item.cliRange && !satisfies(cliVersion, item.cliRange)) {\n    throw new Error(`${item.name} requires CLI ${item.cliRange}, you have ${cliVersion}`);\n  }\n}","typeGuard":"function isRegistryCompatibilityError(err: unknown): boolean {\n  return err instanceof Error && err.name === 'RegistryCompatibilityError';\n}","tryCatchPattern":"try {\n  await runAdd(opts);\n} catch (err) {\n  if (err instanceof AddError && err.code === 'incompatible-cli') {\n    console.error('Upgrade the CLI, then retry:', err.message);\n  }\n}","preventionTips":["Keep the CLI updated when adopting new catalog items.","In CI, bump the CLI pin in lockstep with registry item upgrades.","Check the item manifest's CLI version range before scripting installs."],"tags":["cli","versioning","registry","compatibility"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}