withastro/astro · error · AstroError

FontFamilyNotFound

FontFamilyNotFound

Error message

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

What it means

AstroError with code `FontFamilyNotFound`, thrown by the `<Font>` component (`packages/astro/components/Font.astro`) when the `cssVariable` prop does not map to any registered font family. The component looks up the variable in `componentDataByCssVariable` (populated by the experimental fonts integration from config); a miss means no font data was registered for that variable, so it cannot emit `<link rel=preload>` or the CSS. The hint states this is usually a typo or an unregistered variable.

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 d081033d5f)

Solutions

1. Confirm the `cssVariable` prop is the exact object returned by your `experimental.fonts` config (e.g. `font Families`/provider's cssVariable), not a hand-written string.
2. Check for typos: the variable name in the component must match the one registered in config.
3. Ensure the experimental fonts integration/provider that defines the family is actually enabled in `astro.config.*`.
4. If the family was intentionally removed, delete the `<Font>` usage that references it.

Example fix

---
// before — passing a string typo instead of the registered variable
<Font cssVariable="--myfont-haed" />

// after — use the cssVariable exported from config and correct the name
import { myHeading } from '../astro.config';
<Font cssVariable={myHeading} preload />
---

import { componentDataByCssVariable } from 'astro:assets';
// before rendering
function isRegisteredCssVariable(v: unknown): boolean {
  return componentDataByCssVariable.has(v as any);
}
if (!isRegisteredCssVariable(cssVariable)) {
  // skip rendering <Font> or log a config error instead of throwing at render time
}

import type { CssVariable } from 'astro:assets';
function isCssVariable(v: unknown): v is CssVariable {
  // CssVariable objects are produced by the fonts config; membership check is the real guard
  return componentDataByCssVariable.has(v as CssVariable);
}

When it happens

Trigger: Passing a `cssVariable` to `<Font>` that was not declared via the `experimental.fonts` config provider; passing a plain string instead of the `CssVariable` symbol/object returned by the config; a typo in the variable name; using `<Font>` before the fonts integration is enabled, or after renaming a variable without updating component usages.

Common situations: A developer enables experimental fonts, renames or removes a family, and forgets to update a `<Font cssVariable={...} />` usage; copy-pasting a `<Font>` call without importing the cssVariable from config; referencing a variable from a different config scope.

Related errors

• FontFileUrlNotFound
• CannotFetchFontFile
• CannotDetermineWeightAndStyleFromFontFile
• UnknownFilesystemError
• CannotExtractFontType

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