{"record":{"id":"eb7091a8f7c1f286","repo":"withastro/astro","slug":"fontfamilynotfound","errorCode":"FontFamilyNotFound","errorMessage":"No data was found for the `\"${family}\"` family passed to the `<Font>` component.","messagePattern":"No data was found for the `\"(.+?)\"` family passed to the `<Font>` component\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/components/Font.astro","lineNumber":16,"sourceCode":"---\nimport { componentDataByCssVariable } from 'virtual:astro:assets/fonts/internal';\nimport { filterPreloads } from '../dist/assets/fonts/core/filter-preloads.js';\nimport { AstroError, AstroErrorData } from '../dist/core/errors/index.js';\n\ninterface Props {\n\t/** The `cssVariable` registered in your Astro configuration. */\n\tcssVariable: import('astro:assets').CssVariable;\n\t/** Whether it should output [preload links](https://web.dev/learn/performance/optimize-web-fonts#preload) or not. */\n\tpreload?: import('astro:assets').FontPreloadFilter;\n}\n\nconst { cssVariable, preload = false } = Astro.props as Props;\nconst data = componentDataByCssVariable.get(cssVariable);\nif (!data) {\n\tthrow new AstroError({\n\t\t...AstroErrorData.FontFamilyNotFound,\n\t\tmessage: AstroErrorData.FontFamilyNotFound.message(cssVariable),\n\t});\n}\n\nconst filteredPreloadData = filterPreloads(data.preloads, preload);\n---\n\n<style set:html={data.css}></style>\n{\n\tfilteredPreloadData?.map(({ url, type }) => (\n\t\t<link rel=\"preload\" href={url} as=\"font\" type={`font/${type}`} crossorigin />\n\t))\n}\n","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/components/Font.astro#L1-L31","documentation":"The experimental `<Font />` component looks up its `cssVariable` prop in a map (`componentDataByCssVariable`) generated at build time from the `experimental.fonts` providers in astro.config. If the variable string is not registered there, the component throws `FontFamilyNotFound` — it cannot emit preload links or the family's CSS for an unknown variable.","triggerScenarios":"Passing `<Font cssVariable=\"--my-font\" />` when no family in `experimental.fonts` declares that cssVariable; a typo or case mismatch versus the config; using `<Font>` in a project where the fonts experiment is not enabled so the virtual module map is empty.","commonSituations":"Renaming the cssVariable in config but not in components; copy-pasting a `<Font>` snippet into another project that lacks the fonts config; disabling the experimental fonts flag while components still import `<Font>`.","solutions":["Register the family in astro.config under `experimental.fonts.providers` with the exact same cssVariable string","Double-check spelling, dashes and case: the lookup is an exact string match against `--`-prefixed variable names","Confirm the fonts experiment is enabled (`experimental: { fonts: [...] }`) so `virtual:astro:assets/fonts/internal` contains data"],"exampleFix":"// before (astro.config.mjs)\nexperimental: { fonts: [{ provider: 'google', cssVariable: '--title-font', name: 'Inter' }] }\n<Font cssVariable=\"--font-title\" />\n\n// after\n<Font cssVariable=\"--title-font\" />","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// derive the union of registered variables from the config type\nconst registeredCssVariables = ['--title-font', '--body-font'] as const;\nfunction isRegisteredCssVariable(v: string): v is (typeof registeredCssVariables)[number] {\n  return (registeredCssVariables as readonly string[]).includes(v);\n}","tryCatchPattern":null,"preventionTips":["Single-source the cssVariable strings: export them from a shared module used by both astro.config and components","Search the codebase for the old name whenever you rename a cssVariable in config","Keep the fonts experiment enabled in every environment that renders <Font>"],"tags":["fonts","experimental","component","css-variable"],"backgroundTag":"unregistered-reference","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}