shadcn-ui/ui · error

Unknown item: "${designSystemConfig.item}".

Error message

Unknown item: "${designSystemConfig.item}".

What it means

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.

Source

Thrown at apps/v4/app/(app)/(create)/lib/v0.ts:188

const transformers: V0Transformer[] = [
  transformIcons as V0Transformer,
  transformMenu as V0Transformer,
  transformRender as V0Transformer,
  transformFont as V0Transformer,
]

function getStyle(designSystemConfig: DesignSystemConfig) {
  return `${designSystemConfig.base}-${designSystemConfig.style}`
}

export async function buildV0Payload(designSystemConfig: DesignSystemConfig) {
  if (designSystemConfig.item) {
    const allowedItems = await getItemsForBase(designSystemConfig.base)
    const isAllowed = allowedItems.some(
      (allowed) => allowed?.name === designSystemConfig.item
    )
    if (!isAllowed) {
      throw new Error(`Unknown item: "${designSystemConfig.item}".`)
    }
  }

  const registryBase = buildRegistryBase(designSystemConfig)
  const normalizedFontHeading =
    designSystemConfig.fontHeading === designSystemConfig.font
      ? "inherit"
      : designSystemConfig.fontHeading

  // Only buildComponentFiles is async — run sync builders directly.
  const globalsCss = buildGlobalsCss(
    registryBase,
    designSystemConfig.font,
    normalizedFontHeading
  )
  const layoutFile = buildLayoutFile(designSystemConfig, normalizedFontHeading)
  const componentFiles = await buildComponentFiles(designSystemConfig)

View on GitHub (pinned to efac598707)

Solutions

1. Call getItemsForBase(config.base) and confirm the item is listed before calling buildV0Payload.
2. If the item is missing, either drop designSystemConfig.item or switch to a base that includes it.
3. Re-validate item whenever base changes.

Example fix

// before
buildV0Payload({ ...config, item: "nonexistent" })

// after
const allowed = (await getItemsForBase(config.base)).map((i) => i?.name).filter(Boolean)
const item = allowed.includes(wantedName) ? wantedName : undefined
buildV0Payload({ ...config, item })

const allowed = (await getItemsForBase(config.base))
  .map((i) => i?.name)
  .filter(Boolean) as string[]
if (config.item && !allowed.includes(config.item)) {
  config = { ...config, item: undefined } // or pick allowed[0]
}

async function isAllowedItem(base: string, name: string): Promise<boolean> {
  const items = await getItemsForBase(base)
  return items.some((i) => i?.name === name)
}

try {
  await buildV0Payload(config)
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Unknown item")) {
    // prompt user to pick a valid item for this base
  } else throw e
}

When it happens

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

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

Related errors

• Base color "${baseColorName}" or theme "${themeName}" not fo
• Font "${designSystemConfig.font}" not found
• Failed to fetch registry item: ${response.statusText}
• Base color "${config.baseColor}" or theme "${config.theme}"
• Base "${config.base}" or icon library "${config.iconLibrary}

AI-assisted analysis of shadcn-ui/ui@efac598707 (2026-08-12). Data as JSON: /api/errors/38d967f1ae05f7cf. Report an issue: GitHub.