{"record":{"id":"12de1b838cc72965","repo":"heygen-com/hyperframes","slug":"unknown-item","errorCode":"unknown-item","errorMessage":"${err instanceof Error ? err.message : String(err)}","messagePattern":"\\$\\{err instanceof Error \\? err\\.message : String\\(err\\)\\}","errorType":"validation","errorClass":"AddError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/add.ts","lineNumber":220,"sourceCode":"export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {\n  const projectDir = resolve(opts.projectDir);\n\n  // 1. Load (or write default) project config.\n  let config = loadProjectConfig(projectDir);\n  const hasConfig = existsSync(projectConfigPath(projectDir));\n  if (!hasConfig && existsSync(resolve(projectDir, \"index.html\"))) {\n    writeProjectConfig(projectDir, DEFAULT_PROJECT_CONFIG);\n    config = DEFAULT_PROJECT_CONFIG;\n  }\n\n  // 2. Resolve the requested item and its transitive registryDependencies.\n  //    The list comes back topologically sorted: dependencies first, the\n  //    requested item last.\n  let resolved: RegistryItem[];\n  try {\n    resolved = await resolveItemWithDependencies(opts.name, { baseUrl: config.registry });\n  } catch (err) {\n    throw new AddError(err instanceof Error ? err.message : String(err), \"unknown-item\");\n  }\n  // `resolveItemWithDependencies` always pushes the requested item last (or throws),\n  // so the final element is the item the user asked for.\n  const item = resolved[resolved.length - 1]!;\n\n  if (item.type === \"hyperframes:example\") {\n    throw new AddError(\n      `\"${item.name}\" is an example — use \\`hyperframes init <dir> --example ${item.name}\\` instead.`,\n      \"example-type\",\n    );\n  }\n\n  // 3. Compatibility-gate every item we're about to install (dependencies\n  //    included) before writing anything.\n  const warnings = assertCompatibleOrThrow(resolved, opts.cliVersion);\n\n  // 4. Remap targets per project config — each item by its own type.\n  const installPlan: RegistryItem[] = resolved.map((resolvedItem) => ({","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/add.ts#L202-L238","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the exact name: `hyperframes add --list` or check the catalog at the configured registry URL.","Check connectivity to the registry base URL (curl -i <registry>/index.json).","If the item was renamed, search the catalog for the new name.","Confirm hyperframes.json#registry points at the registry that actually hosts the item."],"exampleFix":"# before: typo / wrong registry\n$ hyperframes add claude-code-windo\n\n# after: correct name from the catalog\n$ hyperframes add claude-code-window","handlingStrategy":"validation","validationCode":"// Pre-check: confirm the item exists in the registry index before installing\nasync function itemExists(name: string, registry: string): Promise<boolean> {\n  const res = await fetch(`${registry}/index.json`);\n  const idx = await res.json();\n  return Array.isArray(idx) && idx.some((i: any) => i.name === name);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runAdd({ name, projectDir });\n} catch (err) {\n  if (err instanceof AddError && err.code === 'unknown-item') {\n    // list available names and re-prompt\n  }\n}","preventionTips":["Confirm the exact name via `hyperframes add --list` or the catalog page.","Ensure hyperframes.json#registry points at the registry hosting the item.","Run with network access when resolving new items."],"tags":["cli","registry","network","resolution"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}