Fix: Font Family Not Found in Astro's Font Component

Astro shows “Font family not found” when the <Font /> component from astro:assets is given a cssVariable that isn’t defined in the fonts option of astro.config.mjs. The message says no data was found for the family “passed to the <Font> component”, and the hint names the usual cause: “This is often caused by a typo. Check that the <Font /> component is using a cssVariable specified in your config.”

Key Takeaways

• <Font cssVariable="--font-inter" /> must match cssVariable: '--font-inter' in config exactly.
• Include the leading --.
• The component looks up by cssVariable, not by the font’s name.
• Restart the dev server after changing the fonts config.

Matching config and component

// astro.config.mjs
import { defineConfig, fontProviders } from 'astro/config';

export default defineConfig({
  fonts: [
    {
      provider: fontProviders.google(),
      name: 'Inter',
      cssVariable: '--font-inter',
    },
  ],
});

---
// src/layouts/BaseLayout.astro
import { Font } from 'astro:assets';
---
<head>
  <Font cssVariable="--font-inter" preload />
</head>

Common mismatches

<Font cssVariable="font-inter" />    <!-- missing -- -->
<Font cssVariable="--font-Inter" />  <!-- case differs -->
<Font cssVariable="Inter" />         <!-- used the name, not the variable -->

All three fail. Copy the value from config rather than retyping it.

After renaming a font

When you switch fonts, update all three places:

1. cssVariable in the fonts config.
2. Every <Font cssVariable="..." />.
3. CSS that uses the variable: font-family: var(--font-inter);.

Keeping the variable generic (--font-body, --font-display) avoids this entirely: swap the name in config and nothing else changes.

fonts: [
  { provider: fontProviders.google(), name: 'Fraunces', cssVariable: '--font-display' },
  { provider: fontProviders.google(), name: 'Inter', cssVariable: '--font-body' },
],

Other font errors

• “Cannot fetch the given font file”: a local font path is wrong, or the provider couldn’t be reached during the build.
• The font loads but looks wrong: check the weights and styles you requested include the ones your CSS uses.

The Fonts API setup, including fallbacks and preloading, is covered in the Astro styling guide, and its performance side in the Astro performance guide. Theme-specific font settings are in the styling docs for Komal themes. The Astro fonts guide lists every provider and option.

FAQ

Do I still need @font-face rules?

No. The Fonts API generates them and the fallback font metrics. Your CSS only uses the variable.

Can I use local font files?

Yes, with the local font provider. The cssVariable matching rule is the same.