withastro/astro · error · AstroError

MissingGetFontFileRequestUrl

MissingGetFontFileRequestUrl

Error message

`experimental_getFontFileURL()` requires the request URL with on-demand rendering.

What it means

In the SSR runtime of the experimental Fonts API, root-relative font URLs must be turned absolute by prefixing the current server's origin, which requires the request URL (ssr-runtime-font-file-url-resolver.ts:30). If `experimental_getFontFileURL(url)` is called without the second argument during on-demand rendering, `MissingGetFontFileRequestUrl` is thrown — the resolver cannot know which origin to use.

Solutions

1. Pass the request URL as the 2nd argument: `experimental_getFontFileURL(url, Astro.url)` in `.astro` components, or the request/context URL in endpoints/middleware.
2. Keep the request URL threaded through any wrapper functions instead of hardcoding an origin.
3. If fonts are served from an external `assetsPrefix`, root-relative URLs are already absolute and this path is not taken — configure `assetsPrefix` when fonts live on a CDN.

Example fix

// before — no request URL
const fileUrl = experimental_getFontFileURL(fontUrl);

// after — request URL supplied
const fileUrl = experimental_getFontFileURL(fontUrl, Astro.url);

// in any wrapper around experimental_getFontFileURL, require the request URL under SSR
export function getFontUrl(url: string, requestUrl: URL | undefined) {
  if (import.meta.env.SSR && url.startsWith('/') && !requestUrl) {
    throw new Error('experimental_getFontFileURL requires the request URL in on-demand rendering');
  }
  return experimental_getFontFileURL(url, requestUrl);
}

const hasRequestUrl = (requestUrl: URL | undefined): requestUrl is URL =>
  requestUrl instanceof URL && requestUrl.origin.startsWith('http');

When it happens

Trigger: On-demand rendering (SSR/hybrid) with a root-relative font URL (served by the app itself, no `assetsPrefix`), calling `experimental_getFontFileURL(url)` with only one argument — typically from an API route, middleware, or a component where `Astro.url` was not passed through.

Common situations: Code that worked in static builds (no request URL needed) breaking after switching the page to on-demand rendering; helper functions wrapping the API and dropping the second parameter.

Related errors

• FontFileUrlNotFound
• CannotExtractFontType
• Could not find server component name
• Couldn't find component for route
• FontFamilyNotFound

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

Appendix: source

Thrown at packages/astro/src/assets/fonts/infra/ssr-runtime-font-file-url-resolver.ts:30

	constructor({
		urls,
	}: {
		urls: Set<string>;
	}) {
		this.#urls = urls;
	}

	resolve(url: string, requestUrl: URL | undefined): string | null {
		if (!this.#urls.has(url)) {
			return null;
		}
		// assetsPrefix
		if (!url.startsWith('/')) {
			return url;
		}
		// We need the request URL to call the current server
		if (!requestUrl) {
			throw new AstroError(MissingGetFontFileRequestUrl);
		}
		return `${requestUrl.origin}${url}`;
	}
}

View on GitHub (pinned to 52e6c34790)