withastro/astro · error · AstroError

FailedToFetchRemoteImageDimensions

FailedToFetchRemoteImageDimensions

Error message

Failed to get the dimensions for ${url}.

What it means

`inferRemoteSize()` streams a remote image to read its dimensions (used by `getImage`/`<Image>` for remote sources without explicit width/height). Before anything else it validates the URL with `URL.canParse`; a string that is not a parseable URL (missing protocol, spaces, malformed) fails immediately with FailedToFetchRemoteImageDimensions.

Solutions

1. Use a fully-qualified URL including protocol: `https://example.com/image.png`
2. Encode dynamic parts: `new URL(path, base).href` or `encodeURIComponent` on segments before passing as src
3. If the image is local, import it or use a root-relative path instead of the remote path

Example fix

<!-- before -->
<Image src="cdn.example.com/hero.png" alt="Hero" />

<!-- after -->
<Image src="https://cdn.example.com/hero.png" alt="Hero" />

// validate before passing any remote src to <Image>/getImage
function assertValidRemoteUrl(src: string): void {
  if (!URL.canParse(src)) {
    throw new Error(`Invalid image URL: ${src} (include the protocol, e.g. https://)`);
  }
}

function isParseableRemoteUrl(src: string): src is `https://${string}` {
  return URL.canParse(src) && src.startsWith('https://');
}

try {
  const size = await inferRemoteSize(url);
} catch (err) {
  if (err instanceof AstroError && err.code === 'FailedToFetchRemoteImageDimensions') {
    // surface the raw URL to content authors for manual fixing
    throw new Error(`Remote image URL is invalid or unreachable: ${url}`);
  }
  throw err;
}

When it happens

Trigger: `<Image src="example.com/image.png" />` (no https:// prefix); a src with unencoded spaces or invalid characters; template-built URLs that end up empty or malformed; passing a relative path to the remote-image path.

Common situations: Forgetting the protocol when moving from local `/img.png` to remote images; URLs copy-pasted with smart quotes or trailing punctuation; CMS fields that return null rendered as the string 'null'.

Related errors

• NoImageMetadata
• RemoteImageNotAllowed
• ⚠️ Astro could not optimize image
• ⚠️ Astro expected an SVG for
• GetImageNotUsedOnServer

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

Appendix: source

Thrown at packages/astro/src/assets/utils/remoteProbe.ts:23

import { imageMetadata } from './metadata.js';
import { fetchWithRedirects } from './redirectValidation.js';

type RemoteImageConfig = Pick<AstroConfig['image'], 'domains' | 'remotePatterns'>;

/**
 * Infers the dimensions of a remote image by streaming its data and analyzing it progressively until sufficient metadata is available.
 *
 * @param {string} url - The URL of the remote image from which to infer size metadata.
 * @param {RemoteImageConfig} [imageConfig] - Optional image config used to validate remote allowlists.
 * @return {Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>} Returns a promise that resolves to an object containing the image dimensions metadata excluding `src` and `fsPath`.
 * @throws {AstroError} Thrown when the fetching fails or metadata cannot be extracted.
 */
export async function inferRemoteSize(
	url: string,
	imageConfig?: RemoteImageConfig,
): Promise<Omit<ImageMetadata, 'src' | 'fsPath'>> {
	if (!URL.canParse(url)) {
		throw new AstroError({
			...AstroErrorData.FailedToFetchRemoteImageDimensions,
			message: AstroErrorData.FailedToFetchRemoteImageDimensions.message(url),
		});
	}

	const allowlistConfig = imageConfig
		? {
				domains: imageConfig.domains ?? [],
				remotePatterns: imageConfig.remotePatterns ?? [],
			}
		: undefined;

	if (!allowlistConfig) {
		const parsedUrl = new URL(url);
		if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
			throw new AstroError({
				...AstroErrorData.FailedToFetchRemoteImageDimensions,
				message: AstroErrorData.FailedToFetchRemoteImageDimensions.message(url),

View on GitHub (pinned to 52e6c34790)