heygen-com/hyperframes · error · AddError

unknown-item

unknown-item

Error message

${err instanceof Error ? err.message : String(err)}

What it means

AddError with code 'unknown-item', thrown when resolveItemWithDependencies rejects while looking up the requested name in the registry. The original error message is preserved verbatim, so a 404 (item not found) and a network failure (registry unreachable) are distinguishable from the message text. Resolution happens after config load and before compatibility gating or any install.

Source

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

export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {
  const projectDir = resolve(opts.projectDir);

  // 1. Load (or write default) project config.
  let config = loadProjectConfig(projectDir);
  const hasConfig = existsSync(projectConfigPath(projectDir));
  if (!hasConfig && existsSync(resolve(projectDir, "index.html"))) {
    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) => ({

View on GitHub (pinned to c2996c8626)

Solutions

  1. Verify the exact name: `hyperframes add --list` or check the catalog at the configured registry URL.
  2. Check connectivity to the registry base URL (curl -i <registry>/index.json).
  3. If the item was renamed, search the catalog for the new name.
  4. Confirm hyperframes.json#registry points at the registry that actually hosts the item.

Example fix

# before: typo / wrong registry
$ hyperframes add claude-code-windo

# after: correct name from the catalog
$ hyperframes add claude-code-window
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check: confirm the item exists in the registry index before installing
async function itemExists(name: string, registry: string): Promise<boolean> {
  const res = await fetch(`${registry}/index.json`);
  const idx = await res.json();
  return Array.isArray(idx) && idx.some((i: any) => i.name === name);
}

Try / catch

try {
  await runAdd({ name, projectDir });
} catch (err) {
  if (err instanceof AddError && err.code === 'unknown-item') {
    // list available names and re-prompt
  }
}

Prevention

When it happens

Trigger: The item name is misspelled or does not exist in the configured registry; the registry base URL is unreachable (DNS, 5xx, offline); the registry index is corrupted or returned an unexpected shape; a tag/group alias resolves to nothing.

Common situations: Typo in the block name; pointing hyperframes.json#registry at a private registry that lacks the item; running offline; the item was renamed or removed in a newer registry revision.

Related errors

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