withastro/astro · error · AstroError

FontFamilyNotFound

FontFamilyNotFound

Error message

No data was found for the `"${family}"` family passed to the `<Font>` component.

What it means

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.

Solutions

1. Register the family in astro.config under `experimental.fonts.providers` with the exact same cssVariable string
2. Double-check spelling, dashes and case: the lookup is an exact string match against `--`-prefixed variable names
3. Confirm the fonts experiment is enabled (`experimental: { fonts: [...] }`) so `virtual:astro:assets/fonts/internal` contains data

Example fix

// before (astro.config.mjs)
experimental: { fonts: [{ provider: 'google', cssVariable: '--title-font', name: 'Inter' }] }
<Font cssVariable="--font-title" />

// after
<Font cssVariable="--title-font" />

// derive the union of registered variables from the config type
const registeredCssVariables = ['--title-font', '--body-font'] as const;
function isRegisteredCssVariable(v: string): v is (typeof registeredCssVariables)[number] {
  return (registeredCssVariables as readonly string[]).includes(v);
}

When it happens

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

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

Related errors

• FontFileUrlNotFound
• MissingGetFontFileRequestUrl
• Server address unavailable, this should not happen. Open an…
• Several font families have been registered for the
• These families will not be merged together. The last…

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/eb7091a8f7c1f286. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/components/Font.astro:16

---
import { componentDataByCssVariable } from 'virtual:astro:assets/fonts/internal';
import { filterPreloads } from '../dist/assets/fonts/core/filter-preloads.js';
import { AstroError, AstroErrorData } from '../dist/core/errors/index.js';

interface Props {
	/** The `cssVariable` registered in your Astro configuration. */
	cssVariable: import('astro:assets').CssVariable;
	/** Whether it should output [preload links](https://web.dev/learn/performance/optimize-web-fonts#preload) or not. */
	preload?: import('astro:assets').FontPreloadFilter;
}

const { cssVariable, preload = false } = Astro.props as Props;
const data = componentDataByCssVariable.get(cssVariable);
if (!data) {
	throw new AstroError({
		...AstroErrorData.FontFamilyNotFound,
		message: AstroErrorData.FontFamilyNotFound.message(cssVariable),
	});
}

const filteredPreloadData = filterPreloads(data.preloads, preload);
---

<style set:html={data.css}></style>
{
	filteredPreloadData?.map(({ url, type }) => (
		<link rel="preload" href={url} as="font" type={`font/${type}`} crossorigin />
	))
}

View on GitHub (pinned to 52e6c34790)