withastro/astro · error · AstroError

CannotExtractFontType

CannotExtractFontType

Error message

An error occurred while trying to extract the font type from ${url}.

What it means

Thrown by NodeFontTypeExtractor.extract when the file extension of a font URL is not a recognized font type. The extractor takes the extension via extname(url), strips the dot, and validates it with isFontType(); any unrecognized extension is reported as CannotExtractFontType with the full url, carrying a cause string naming the bad extension.

Source

Thrown at packages/astro/src/assets/fonts/infra/node-font-type-extractor.ts:11

import { extname } from 'node:path';
import { AstroError, AstroErrorData } from '../../../core/errors/index.js';
import type { FontTypeExtractor } from '../definitions.js';
import type { FontType } from '../types.js';
import { isFontType } from '../utils.js';

export class NodeFontTypeExtractor implements FontTypeExtractor {
	extract(url: string): FontType {
		const extension = extname(url).slice(1);
		if (!isFontType(extension)) {
			throw new AstroError(
				{
					...AstroErrorData.CannotExtractFontType,
					message: AstroErrorData.CannotExtractFontType.message(url),
				},
				{ cause: `Unexpected extension, got "${extension}"` },
			);
		}
		return extension;
	}
}

View on GitHub (pinned to d081033d5f)

Solutions

1. Confirm the URL resolves to a real font binary (.woff2/.woff/.ttf/.otf), not a CSS or HTML wrapper.
2. Copy the full URL from the error and open it in a browser to inspect what is served.
3. If the URL has query parameters, ensure the path portion still ends in a recognized extension.
4. Switch the source to a provider/URL that serves the raw font file.

Example fix

// before
src: 'https://example.com/styles/fonts.css'

// after
src: 'https://example.com/files/MyFont.woff2'

import { extname } from 'node:path';
const FONT_EXT = new Set(['woff', 'woff2', 'ttf', 'otf', 'eot']);
function hasFontExtension(url: string): boolean {
  return FONT_EXT.has(extname(new URL(url, 'http://x').pathname).slice(1).toLowerCase());
}

try { extractor.extract(url); }
catch (e) {
  if (e instanceof AstroError && e.code === 'CannotExtractFontType') {
    // switch to a URL that serves a real font binary
  }
}

When it happens

Trigger: Calling extract(url) where the URL's path extension is not in the set of valid font extensions (e.g. .woff2/.woff/.ttf/.otf). A URL with no extension, an extension like .txt, .xml, .css, or a query-string-suffixed path parsed by extname will all trigger it.

Common situations: A font provider URL that points at a CSS file or HTML page instead of the actual font binary, a typo'd file extension, a URL whose real extension is after a query/hash that extname mishandles, or an upstream font source that redirects to a non-font asset.

Related errors

• CannotFetchFontFile
• CannotDetermineWeightAndStyleFromFontFile
• UnknownFilesystemError
• UnknownFilesystemError
• EnvInvalidVariables

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