Fix: Expected src to be an Image in Astro

What Causes This Error?

This error occurs when you pass an invalid value to the src prop of the Image component or getImage() function. The src must be either an imported image or a valid URL string.

The Problem

---
import { Image } from 'astro:assets';

// ❌ Passing string path instead of import
const imagePath = '../assets/photo.jpg';
---

<Image src={imagePath} alt="Photo" />

---
import { Image } from 'astro:assets';

// ❌ Passing undefined or null
const image = undefined;
---

<Image src={image} alt="Photo" />

The Fix

Import the Image

---
import { Image } from 'astro:assets';
// ✅ Import the image
import photo from '../assets/photo.jpg';
---

<Image src={photo} alt="Photo" />

Use URL String for Remote Images

---
import { Image } from 'astro:assets';
---

<!-- ✅ Remote URL with dimensions -->
<Image
  src="https://example.com/photo.jpg"
  alt="Photo"
  width={800}
  height={600}
/>

Common Scenarios

Dynamic Images with Glob

---
import { Image } from 'astro:assets';

// ✅ Use import.meta.glob for dynamic imports
const images = import.meta.glob<{ default: ImageMetadata }>(
  '../assets/gallery/*.{jpg,png,webp}'
);

const imagePath = '../assets/gallery/photo1.jpg';
const imageModule = await images[imagePath]();
---

<Image src={imageModule.default} alt="Gallery photo" />

Content Collection Images

---
import { Image } from 'astro:assets';
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---

{posts.map((post) => (
  <!-- ✅ Content collection images are already imported -->
  <Image src={post.data.coverImage} alt={post.data.title} />
))}

Check for Undefined

---
import { Image } from 'astro:assets';
import fallbackImage from '../assets/fallback.jpg';

const { image } = Astro.props;
---

<!-- ✅ Provide fallback for undefined -->
<Image src={image || fallbackImage} alt="Content" />

Props with Images

---
// Component.astro
import { Image } from 'astro:assets';
import type { ImageMetadata } from 'astro';

interface Props {
  image: ImageMetadata;
  alt: string;
}

const { image, alt } = Astro.props;
---

<Image src={image} alt={alt} />

---
// Usage
import Component from './Component.astro';
import photo from '../assets/photo.jpg';
---

<Component image={photo} alt="A photo" />

getImage Function

---
import { getImage } from 'astro:assets';
import originalImage from '../assets/photo.jpg';

// ✅ Pass imported image to getImage
const optimized = await getImage({
  src: originalImage,
  width: 800,
});
---

<img src={optimized.src} alt="Photo" {...optimized.attributes} />

Conditional Image Rendering

---
import { Image } from 'astro:assets';
import defaultImage from '../assets/default.jpg';

const { customImage } = Astro.props;
const hasCustomImage = customImage && typeof customImage !== 'string';
---

{hasCustomImage ? (
  <Image src={customImage} alt="Custom" />
) : (
  <Image src={defaultImage} alt="Default" />
)}

Valid src Types

---
import { Image } from 'astro:assets';
import localImage from '../assets/photo.jpg';

// ✅ Valid: Imported image (ImageMetadata)
<Image src={localImage} alt="Photo" />

// ✅ Valid: Remote URL string with dimensions
<Image src="https://example.com/photo.jpg" alt="Photo" width={800} height={600} />

// ❌ Invalid: Local path string
<Image src="../assets/photo.jpg" alt="Photo" />

// ❌ Invalid: undefined, null, number, object
<Image src={undefined} alt="Photo" />
---

Quick Checklist

• Import local images, don’t use path strings
• Remote images use URL strings with dimensions
• Check for undefined before rendering
• Use import.meta.glob for dynamic imports
• Content collection images are pre-imported