shadcn-ui/ui · critical

Unknown font definition: ${name}

Error message

Unknown font definition: ${name}

What it means

Thrown by createFontOption() when the FontName passed to it has no matching entry in FONT_DEFINITIONS (imported from @/lib/font-definitions). Because the FONTS array is built eagerly by calling createFontOption at module load, an unknown name crashes at import/bundle time rather than at call time. This is always a data-integrity mismatch between the font registry and the FONTS export list.

Source

Thrown at apps/v4/app/(app)/(create)/lib/fonts.ts:17

import { FONT_DEFINITIONS, type FontName } from "@/lib/font-definitions"

type CreateFont = {
  family: string
  import: string
  previewVariable: string
  style: {
    fontFamily: string
  }
  variable: string
}

function createFontOption(name: FontName) {
  const definition = FONT_DEFINITIONS.find((font) => font.name === name)

  if (!definition) {
    throw new Error(`Unknown font definition: ${name}`)
  }

  return {
    name: definition.title,
    value: definition.name,
    font: {
      family: definition.family,
      import: definition.import,
      previewVariable: definition.previewVariable,
      style: {
        fontFamily: `var(${definition.previewVariable}), ${definition.family}`,
      },
      variable: definition.registryVariable,
    } satisfies CreateFont,
    type: definition.type,
  } as const
}

View on GitHub (pinned to efac598707)

Solutions

1. Open @/lib/font-definitions and confirm the font exists in FONT_DEFINITIONS with a name field that matches exactly (hyphenation and case).
2. Correct the string passed to createFontOption in fonts.ts to match the registered name.
3. If adding a genuinely new font, add its full definition to FONT_DEFINITIONS first, then append createFontOption("<name>") to FONTS.

Example fix

// before
createFontOption("my-font") // FONT_DEFINITIONS has no "my-font"

// after (option A): use a registered name
createFontOption("inter")

// after (option B): register it first in font-definitions.ts
//   { name: "my-font", title: "My Font", family: "...", ... }

import { FONT_DEFINITIONS } from "@/lib/font-definitions"
const registered = new Set(FONT_DEFINITIONS.map((f) => f.name))
function assertFontKnown(name: string) {
  if (!registered.has(name as never)) {
    throw new Error(`Unknown font definition: ${name}`)
  }
}
// assertFontKnown("my-font") before createFontOption("my-font")

import { FONT_DEFINITIONS, type FontName } from "@/lib/font-definitions"
const KNOWN = new Set(FONT_DEFINITIONS.map((f) => f.name))
function isFontName(name: string): name is FontName {
  return KNOWN.has(name)
}

When it happens

Trigger: Adding createFontOption("my-font") to the FONTS array before registering "my-font" in FONT_DEFINITIONS; renaming a font in font-definitions.ts but not in fonts.ts (or vice versa); a typo or casing difference in the name string passed to createFontOption.

Common situations: Contributing a new font to the v4 style builder; splitting font metadata between font-definitions.ts and fonts.ts; copy-pasting an existing createFontOption line and changing only the name.

Related errors

• Base color "${baseColorName}" or theme "${themeName}" not fo
• Base color "${config.baseColor}" or theme "${config.theme}"
• Base "${config.base}" or icon library "${config.iconLibrary}
• Unknown item: "${designSystemConfig.item}".
• Font "${designSystemConfig.font}" not found

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