heygen-com/hyperframes · error · RegistryCompatibilityError

Registry item "${item.name}" declares invalid minCliVersion

Error message

Registry item "${item.name}" declares invalid minCliVersion "${minCliVersion}".

What it means

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).

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. Fix the item's minCliVersion to a valid semver (e.g. '0.6.80') in its registry metadata
2. Remove minCliVersion from the item to skip the gate entirely
3. If you don't control the item, report it to the registry maintainer
4. Develop against the dev CLI (0.0.0-dev) which bypasses the check

Example fix

// before
{ "name": "my-block", "minCliVersion": "next" }
// after
{ "name": "my-block", "minCliVersion": "0.6.80" }

import { validate } from "compare-versions";
function validMinCliVersion(v: string | undefined): boolean {
  if (!v) return true;
  try { validate(v); return true; } catch { return false; }
}

import { validate } from "compare-versions";
function isValidSemver(v: unknown): v is string {
  return typeof v === "string" && (() => { try { validate(v); return true; } catch { return false; } })();
}

try {
  gateRegistryItemsCompatibility(items);
} catch (e) {
  if (e instanceof RegistryCompatibilityError && e.message.includes("declares invalid minCliVersion")) {
    // strip/fix minCliVersion in the offending item, then retry
  }
  throw e;
}

When it happens

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

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

Related errors

• incompatible-cli
• Registry item "${item.name}" requires hyperframes >= ${minCl
• install-failed
• unknown-item
• example-type

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