heygen-com/hyperframes · error · RegistryCompatibilityError

Registry item "${item.name}" requires hyperframes >= ${minCl

Error message

Registry item "${item.name}" requires hyperframes >= ${minCliVersion} (current: ${currentCliVersion}). Run `npx hyperframes@latest add ${item.name}` or upgrade your installed hyperframes CLI.

What it means

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.

Source

Thrown at packages/cli/src/registry/compatibility.ts:73

 * Compatibility-gate a set of resolved items (e.g. an item plus its transitive
 * `registryDependencies`) before any of them are installed. Throws a
 * `RegistryCompatibilityError` on the first item that requires a newer CLI, so
 * a partial install never happens; returns the accumulated (non-fatal)
 * deprecation warnings from every item.
 *
 * Every install path — `add`, template fetch, and the Studio "add block"
 * action — funnels through this so a dependency that ships `minCliVersion` is
 * rejected uniformly, not just by `hyperframes add`.
 */
export function gateRegistryItemsCompatibility(
  items: RegistryItem[],
  currentCliVersion = VERSION,
): string[] {
  const warnings: string[] = [];
  for (const item of items) {
    const result = checkRegistryItemCompatibility(item, currentCliVersion);
    if (result.error) {
      throw new RegistryCompatibilityError(result.error);
    }
    warnings.push(...result.warnings);
  }
  return warnings;
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Upgrade and retry with the command in the message: `npx hyperframes@latest add <item.name>`
2. Update your global CLI: `npm i -g hyperframes@latest`
3. Pin your project scripts to hyperframes@latest so npx always fetches the newest
4. Develop against the dev build (0.0.0-dev) to bypass the gate locally

Example fix

// before
npx hyperframes@0.6.79 add fancy-block   # block needs >=0.6.80
// after
npx hyperframes@latest add fancy-block

import { compareVersions } from "compare-versions";
function cliSatisfies(current: string, min: string | undefined): boolean {
  if (!min || current === "0.0.0-dev") return true;
  return compareVersions(current, min) >= 0;
}

try {
  gateRegistryItemsCompatibility(items, currentVersion);
} catch (e) {
  if (e instanceof RegistryCompatibilityError && e.message.includes("requires hyperframes >=")) {
    // re-run via `npx hyperframes@latest add <name>` and abort
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• incompatible-cli
• Registry item "${item.name}" declares invalid minCliVersion
• Unsupported chain version: ${String(obj.version)}
• install-failed
• unknown-item

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/f0fb4fd61168e7af. Report an issue: GitHub.