heygen-com/hyperframes · error · AddError

incompatible-cli

incompatible-cli

Error message

${err.message}

What it means

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.

Source

Thrown at packages/cli/src/commands/add.ts:170

      | "wrong-type"
      | "install-failed"
      | "example-type"
      | "incompatible-cli",
  ) {
    super(message);
    this.name = "AddError";
  }
}

// Compatibility-gate a set of resolved items before any install runs, mapping
// the shared gate's error into an AddError so the command surfaces the right
// exit code. Returns the accumulated (non-fatal) warnings from every item.
function assertCompatibleOrThrow(items: RegistryItem[], cliVersion?: string): string[] {
  try {
    return gateRegistryItemsCompatibility(items, cliVersion);
  } catch (err) {
    if (err instanceof RegistryCompatibilityError) {
      throw new AddError(err.message, "incompatible-cli");
    }
    throw err;
  }
}

// Install a topologically-ordered plan (dependencies first, requested item
// last). The installer validates every target before any write; a failure on
// any item surfaces as an install-failed AddError. Returns all written paths.
async function installAll(
  installPlan: RegistryItem[],
  destDir: string,
  baseUrl: string | undefined,
  force: boolean,
): Promise<{ written: string[]; preserved: string[] }> {
  const written: string[] = [];
  const preserved: string[] = [];
  try {
    for (const planItem of installPlan) {

View on GitHub (pinned to c2996c8626)

Solutions

1. Upgrade the CLI to the version the gate names: `npm i -g hyperframes@latest` (or the specific version).
2. If you cannot upgrade, pin an older version of the block/component that is compatible with your CLI.
3. Check the item's registry-item.json for the declared version range and confirm against `hyperframes --version`.

Example fix

# before: old CLI, new block
$ hyperframes --version
0.3.1
$ hyperframes add new-block   # incompatible-cli

# after: align versions
$ npm i -g hyperframes@latest
$ hyperframes add new-block

// Pre-check CLI version against the item's declared range before installing
import { satisfies } from 'semver';
function assertCliCompatible(item: RegistryItem, cliVersion: string) {
  if (item.cliRange && !satisfies(cliVersion, item.cliRange)) {
    throw new Error(`${item.name} requires CLI ${item.cliRange}, you have ${cliVersion}`);
  }
}

function isRegistryCompatibilityError(err: unknown): boolean {
  return err instanceof Error && err.name === 'RegistryCompatibilityError';
}

try {
  await runAdd(opts);
} catch (err) {
  if (err instanceof AddError && err.code === 'incompatible-cli') {
    console.error('Upgrade the CLI, then retry:', err.message);
  }
}

When it happens

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

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

Related errors

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

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