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

For string (remote) `src`s, `verifyOptions()` requires explicit dimensions because nothing at build time knows the intrinsic size — missing width/height would cause cumulative layout shift (packages/astro/src/assets/services/service.ts:181). One or both missing throws `MissingImageDimension`, naming which attribute(s) are absent.

Solutions

1. Add both `width` and `height` matching the image's aspect ratio (one can be derived at render time if you know the ratio).
2. With `getImage()`, set `inferSize: true` (and allowlist the domain) so Astro probes the real dimensions for you.
3. Better: download the image into `src/` and ESM-import it — dimensions are then read from the file automatically.

Example fix

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

// after
<Image src="https://cdn.example.com/hero.png" alt="Hero" width={1200} height={630} />

// for remote string sources, require both dimensions up front
if (typeof src === 'string' && src.startsWith('http')) {
  if (!width || !height) {
    throw new Error(`Remote image ${src} needs both width and height (or inferSize)`);
  }
}

type WithDimensions<T> = T & { width: number; height: number };

function hasBothDimensions(o: { width?: number; height?: number }): o is WithDimensions<{}> {
  return typeof o.width === 'number' && typeof o.height === 'number';
}

When it happens

Trigger: `<Image src="https://cdn.example.com/hero.png" alt="Hero" />` with no width/height, or with only one of the two; also `getImage({ src: remoteUrl })` without `inferSize`.

Common situations: Migrating remote `<img>` tags to `<Image>` and forgetting dimensions; CMS images whose size is only known at runtime; responsive designs assuming auto-sizing.

Related errors

• ExpectedImage
• LocalImageUsedWrongly
• RemoteImageNotAllowed
• ⚠️ Astro could not optimize image
• ⚠️ Astro expected an SVG for

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

Appendix: source

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

		) {
			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 e294953aa8)