Fix: Missing Image Dimensions in Astro

Astro shows “Missing image dimensions” when an <Image /> or <Picture /> gets a remote URL (or a string path) without both width and height. For imported local images Astro reads the size from the file, but for a URL it can’t know the size at build time, and it needs it to prevent layout shift. The message says: “When using remote images, both dimensions are required in order to avoid CLS.” Add width and height, add inferSize, or import the file if it’s in your project.

Key Takeaways

• Remote images need explicit width and height, or inferSize.
• If the image is in src/, import it instead of passing a path string.
• inferSize fetches the image at build time to read its size, which slows builds slightly.
• The dimensions set the aspect ratio; CSS can still make the image responsive.

Fix 1: give both dimensions

---
import { Image } from 'astro:assets';
---
<Image
  src="https://images.example-cms.com/team.jpg"
  alt="The team at the 2026 offsite"
  width={1200}
  height={800}
/>

Use the real aspect ratio of the source. If you only know the width, check the file’s metadata or your CMS, which usually returns both.

Fix 2: let Astro measure it

<Image src={post.coverUrl} alt={post.coverAlt} inferSize />

Astro downloads the image header at build time to read its size. This works well for CMS images whose sizes vary, at the cost of a request per image during the build. The domain must also be allowed; otherwise you’ll see Remote image is not allowed.

Fix 3: import local images

The error hint covers this case: “If your image is inside your src folder, you probably meant to import it instead.”

---
// Wrong: string path to a local file
// <Image src="/src/assets/hero.jpg" alt="..." />

// Right
import hero from '../assets/hero.jpg';
---
<Image src={hero} alt="Product dashboard" />

Imported images give Astro the size, format and file, so it can also optimise them. See Local images must be imported for the related error.

Images in public/

Files in public/ are served as-is and aren’t processed. If you pass /images/photo.jpg (a public/ path) to <Image />, Astro treats it like a remote URL and needs dimensions. Either add width and height, or move the file to src/assets/ and import it to get optimisation too.

Why dimensions matter

Without dimensions, the browser can’t reserve space for the image before it loads, so text jumps when it appears. That jump is measured as Cumulative Layout Shift, one of the Core Web Vitals. The Astro performance guide covers it, and responsive images in Astro shows how to make sized images fluid. The official entry is in the Astro error reference.

FAQ

Will setting width and height make my image a fixed size?

No. They set the intrinsic size and aspect ratio. With layout="constrained" or CSS like width: 100%; height: auto, the image still scales.

Does inferSize work for every remote image?

It works when the URL is reachable during the build and the domain is allowed in image.domains or image.remotePatterns.