withastro/astro · error · AstroError

MissingImageDimension

MissingImageDimension

Error message

Missing ${missingDimension === 'both' ? 'width and height attributes' : `${missingDimension} attribute`} for ${imageURL}. When using remote images, both dimensions are required in order to avoid CLS.

What it means

Thrown by verifyOptions() for remote (non-imported) images when width and/or height are missing. Because the service cannot infer dimensions from a remote file without a fetch, both width and height are mandatory for remote string sources to avoid layout shift (CLS).

Source

Thrown at packages/astro/src/assets/services/service.ts:181

		) {
			throw new AstroError({
				...AstroErrorData.LocalImageUsedWrongly,
				message: AstroErrorData.LocalImageUsedWrongly.message(options.src),
			});
		}

		// For remote images, width and height are explicitly required as we can't infer them from the file
		let missingDimension: 'width' | 'height' | 'both' | undefined;
		if (!options.width && !options.height) {
			missingDimension = 'both';
		} else if (!options.width && options.height) {
			missingDimension = 'width';
		} else if (options.width && !options.height) {
			missingDimension = 'height';
		}

		if (missingDimension) {
			throw new AstroError({
				...AstroErrorData.MissingImageDimension,
				message: AstroErrorData.MissingImageDimension.message(missingDimension, options.src),
			});
		}
	} else {
		if (!VALID_SUPPORTED_FORMATS.includes(options.src.format as any)) {
			throw new AstroError({
				...AstroErrorData.UnsupportedImageFormat,
				message: AstroErrorData.UnsupportedImageFormat.message(
					options.src.format,
					options.src.src,
					VALID_SUPPORTED_FORMATS,
				),
			});
		}

		if (options.widths && options.densities) {
			throw new AstroError(AstroErrorData.IncompatibleDescriptorOptions);

View on GitHub (pinned to d081033d5f)

Solutions

1. Provide both width and height for remote images.
2. Use inferSize: true on getImage (and let Astro probe), where supported, to auto-derive dimensions.
3. If using <Image > with a known aspect ratio, compute height from width.
4. For full-bleed images, set explicit width and height in the attributes.

Example fix

// before
<Image src='https://cdn.example.com/photo.jpg' alt='photo' />

// after
<Image src='https://cdn.example.com/photo.jpg' width={1200} height={800} alt='photo' />

function hasBothDimensions(o: { width?: number; height?: number }): boolean {
  return Number.isFinite(o.width) && Number.isFinite(o.height);
}

function hasDimensions(o: unknown): o is { width: number; height: number } {
  return typeof o === 'object' && o !== null
    && Number.isFinite((o as any).width) && Number.isFinite((o as any).height);
}

When it happens

Trigger: Calling the service with a remote string src where neither width nor height is set (missingDimension='both'), only height is set ('width'), or only width is set ('height'). The message names which dimension(s) are missing and the imageURL.

Common situations: Author uses <Image src='https://cdn/x.png' /> without dimensions, or sets only width. Common when migrating from <img> or copying remote URLs into components.

Related errors

• ExpectedImageOptions
• ExpectedImage
• RemoteImageNotAllowed
• ExpectedImage
• UnsupportedImageFormat

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