What causes ""${item.name}" is an example — use `hyperframes init --example ${item.name}` instead." in heygen-com/hyperframes?

Use the command the error prints: `hyperframes init --example `.

heygen-com/hyperframes · error · AddError

example-type

example-type

Error message

"${item.name}" is an example — use `hyperframes init <dir> --example ${item.name}` instead.

What it means

AddError with code 'example-type', thrown after resolution when the requested item's type is 'hyperframes:example'. Examples are full starter projects, not installable blocks/components, so the CLI refuses to add() them and points the user at `hyperframes init <dir> --example <name>`. This guard runs after resolution but before compatibility gating and install.

Source

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

    writeProjectConfig(projectDir, DEFAULT_PROJECT_CONFIG);
    config = DEFAULT_PROJECT_CONFIG;
  }

  // 2. Resolve the requested item and its transitive registryDependencies.
  //    The list comes back topologically sorted: dependencies first, the
  //    requested item last.
  let resolved: RegistryItem[];
  try {
    resolved = await resolveItemWithDependencies(opts.name, { baseUrl: config.registry });
  } catch (err) {
    throw new AddError(err instanceof Error ? err.message : String(err), "unknown-item");
  }
  // `resolveItemWithDependencies` always pushes the requested item last (or throws),
  // so the final element is the item the user asked for.
  const item = resolved[resolved.length - 1]!;

  if (item.type === "hyperframes:example") {
    throw new AddError(
      `"${item.name}" is an example — use \`hyperframes init <dir> --example ${item.name}\` instead.`,
      "example-type",
    );
  }

  // 3. Compatibility-gate every item we're about to install (dependencies
  //    included) before writing anything.
  const warnings = assertCompatibleOrThrow(resolved, opts.cliVersion);

  // 4. Remap targets per project config — each item by its own type.
  const installPlan: RegistryItem[] = resolved.map((resolvedItem) => ({
    ...resolvedItem,
    files: resolvedItem.files.map((f) => ({
      ...f,
      target: remapTarget(resolvedItem, f.target, config.paths),
    })),
  }));

View on GitHub (pinned to c2996c8626)

Solutions

Use the command the error prints: `hyperframes init <dir> --example <item.name>`.
If you actually wanted a block or component with a similar name, search the catalog for the non-example item.
Update any automation that dispatched `add` on an example to branch on item type first.

Example fix

# before: examples are not add-able
$ hyperframes add starter-sizzle

# after: init a new project from the example
$ hyperframes init ./my-video --example starter-sizzle

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check: branch on item type before choosing add vs init
if (item.type === 'hyperframes:example') {
  throw new Error(`Use: hyperframes init <dir> --example ${item.name}`);
}

Type guard

function isExampleItem(item: RegistryItem): boolean {
  return item.type === 'hyperframes:example';
}

Try / catch

try {
  await runAdd(opts);
} catch (err) {
  if (err instanceof AddError && err.code === 'example-type') {
    // switch to `hyperframes init <dir> --example <name>`
  }
}

Prevention

Reserve `add` for blocks and components; use `init` for example starters.
When automating discovery, branch on item.type before dispatching the verb.

When it happens

Trigger: Calling `hyperframes add <example-name>` where the resolved item is typed as an example (e.g. one of the entries under registry/examples). The message names the example and gives the exact init command to use instead.

Common situations: A user finds a starter in the catalog and runs `add` by reflex; tooling auto-discovers items and dispatches the wrong verb; copy-pasting an `add` command from docs that were describing an example.

Related errors

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