{"record":{"id":"38d967f1ae05f7cf","repo":"shadcn-ui/ui","slug":"unknown-item-designsystemconfig-item","errorCode":null,"errorMessage":"Unknown item: \"${designSystemConfig.item}\".","messagePattern":"Unknown item: \"(.+?)\"\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"apps/v4/app/(app)/(create)/lib/v0.ts","lineNumber":188,"sourceCode":"const transformers: V0Transformer[] = [\n  transformIcons as V0Transformer,\n  transformMenu as V0Transformer,\n  transformRender as V0Transformer,\n  transformFont as V0Transformer,\n]\n\nfunction getStyle(designSystemConfig: DesignSystemConfig) {\n  return `${designSystemConfig.base}-${designSystemConfig.style}`\n}\n\nexport async function buildV0Payload(designSystemConfig: DesignSystemConfig) {\n  if (designSystemConfig.item) {\n    const allowedItems = await getItemsForBase(designSystemConfig.base)\n    const isAllowed = allowedItems.some(\n      (allowed) => allowed?.name === designSystemConfig.item\n    )\n    if (!isAllowed) {\n      throw new Error(`Unknown item: \"${designSystemConfig.item}\".`)\n    }\n  }\n\n  const registryBase = buildRegistryBase(designSystemConfig)\n  const normalizedFontHeading =\n    designSystemConfig.fontHeading === designSystemConfig.font\n      ? \"inherit\"\n      : designSystemConfig.fontHeading\n\n  // Only buildComponentFiles is async — run sync builders directly.\n  const globalsCss = buildGlobalsCss(\n    registryBase,\n    designSystemConfig.font,\n    normalizedFontHeading\n  )\n  const layoutFile = buildLayoutFile(designSystemConfig, normalizedFontHeading)\n  const componentFiles = await buildComponentFiles(designSystemConfig)\n","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/apps/v4/app/(app)/(create)/lib/v0.ts#L170-L206","documentation":"buildV0Payload() optionally takes designSystemConfig.item; when set, it must appear among the items returned by getItemsForBase(designSystemConfig.base). The guard prevents generating a v0 payload for a component the chosen base does not ship.","triggerScenarios":"Passing item: \"foo\" where \"foo\" is not returned by getItemsForBase(base); changing base without clearing or updating item; a stale item name after a registry rename.","commonSituations":"Deep-linking to a specific component in the style builder; requesting a component (e.g. charts) on a minimal base that does not include it; programmatic v0 payload generation.","solutions":["Call getItemsForBase(config.base) and confirm the item is listed before calling buildV0Payload.","If the item is missing, either drop designSystemConfig.item or switch to a base that includes it.","Re-validate item whenever base changes."],"exampleFix":"// before\nbuildV0Payload({ ...config, item: \"nonexistent\" })\n\n// after\nconst allowed = (await getItemsForBase(config.base)).map((i) => i?.name).filter(Boolean)\nconst item = allowed.includes(wantedName) ? wantedName : undefined\nbuildV0Payload({ ...config, item })","handlingStrategy":"validation","validationCode":"const allowed = (await getItemsForBase(config.base))\n  .map((i) => i?.name)\n  .filter(Boolean) as string[]\nif (config.item && !allowed.includes(config.item)) {\n  config = { ...config, item: undefined } // or pick allowed[0]\n}","typeGuard":"async function isAllowedItem(base: string, name: string): Promise<boolean> {\n  const items = await getItemsForBase(base)\n  return items.some((i) => i?.name === name)\n}","tryCatchPattern":"try {\n  await buildV0Payload(config)\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"Unknown item\")) {\n    // prompt user to pick a valid item for this base\n  } else throw e\n}","preventionTips":["Populate item pickers from getItemsForBase(base) so the list is always base-correct.","Re-validate item whenever base changes."],"tags":["v0","registry","validation","components"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}