withastro/astro · error · AstroError

MissingGetFontFileRequestUrl

MissingGetFontFileRequestUrl

Error message

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

What it means

Thrown by SSRRuntimeFontFileURLResolver.resolve when an on-demand (SSR) rendering call needs to build an absolute font file URL but no request URL is available. The resolver only knows the request origin if the caller supplies requestUrl; without it, it cannot construct `${requestUrl.origin}${url}` and throws MissingGetFontFileRequestUrl.

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

Solutions

Call experimental_getFontFileURL() only within an on-demand-rendered request handler where the request URL is in scope.
If prerendering, switch the route to static output or pass the request URL explicitly.
Verify the adapter forwards the original request URL into the Astro pipeline.
For non-request contexts, use the static (build-time) font URL instead of the SSR resolver.

Example fix

// before - called at module load, no request
export const url = experimental_getFontFileURL(myFont);

// after - called inside a request handler
export const GET = ({ request }) =>
  new Response(experimental_getFontFileURL(myFont, { requestUrl: new URL(request.url) }));

Defensive patterns

Strategy: type-guard

Validate before calling

function hasRequestUrl(ctx: { request?: Request }): ctx is { request: Request } {
  return !!ctx.request && !!ctx.request.url;
}

Type guard

function hasRequestUrl(ctx: { request?: Request }): ctx is { request: Request } {
  return !!ctx.request && !!ctx.request.url;
}

Try / catch

if (!requestUrl) { /* do not call SSR resolver; use static font URL or 500 */ }
else { resolver.resolve(url, requestUrl); }

Prevention

Only call experimental_getFontFileURL() inside an on-demand request handler.
Pass the request URL explicitly through every layer that resolves font URLs.
Use static output for routes that must compute font URLs without a request.

When it happens

Trigger: Calling resolve(url, requestUrl) where url is a known stored path that starts with '/' (i.e. not an assetsPrefix path) and requestUrl is undefined. This happens in on-demand rendering when experimental_getFontFileURL() is invoked outside a request context.

Common situations: Using experimental_getFontFileURL() during SSR build-time prerendering, in a context without an active request (e.g. a top-level module evaluation or a scheduled job), or with an adapter that does not propagate the request URL to the resolver.

Related errors

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