withastro/astro · error · AstroError

ExpectedImage

ExpectedImage

Error message

Expected `src` property for `getImage` or `<Image />` to be either an ESM imported image or a string with the path of a remote image. Received `${src}` (type: `${typeofOptions}`).\n\nFull serialized options received: `${fullOptions}`.

What it means

Thrown by getImage() when options.src is undefined. After the object-shape check passes, the next guard tests `typeof options.src === 'undefined'` and reports ExpectedImage with the (undefined) src, its type, and the full serialized options.

Source

Thrown at packages/astro/src/assets/internal.ts:59

		globalThis.astroAsset.imageService = service;
		return service;
	}

	return globalThis.astroAsset.imageService;
}

export async function getImage(
	options: UnresolvedImageTransform,
	imageConfig: AstroConfig['image'] & AstroAdapterClientConfig,
): Promise<GetImageResult> {
	if (!options || typeof options !== 'object') {
		throw new AstroError({
			...AstroErrorData.ExpectedImageOptions,
			message: AstroErrorData.ExpectedImageOptions.message(JSON.stringify(options)),
		});
	}
	if (typeof options.src === 'undefined') {
		throw new AstroError({
			...AstroErrorData.ExpectedImage,
			message: AstroErrorData.ExpectedImage.message(
				options.src,
				'undefined',
				JSON.stringify(options),
			),
		});
	}

	if (isImageMetadata(options)) {
		throw new AstroError(AstroErrorData.ExpectedNotESMImage);
	}

	const service = await getConfiguredImageService();

	// If the user inlined an import, something fairly common especially in MDX, or passed a function that returns an Image, await it for them
	const resolvedOptions: ImageTransform = {
		...options,

View on GitHub (pinned to d081033d5f)

Solutions

1. Ensure the options object always includes a src property.
2. Default or validate src before calling: if (!options.src) return;.
3. Check for typos — the property name is exactly `src`.
4. Log options before the call to confirm src is present.

Example fix

// before
getImage({ width: 800, height: 600 })

// after
getImage({ src: importedImage, width: 800, height: 600 })

function hasSrc(o: unknown): o is { src: unknown } {
  return typeof o === 'object' && o !== null && 'src' in o && (o as any).src !== undefined;
}

function hasSrc(o: unknown): o is { src: unknown } {
  return typeof o === 'object' && o !== null && 'src' in o && (o as any).src !== undefined;
}

When it happens

Trigger: Calling getImage({ ... }) where the src property is omitted or explicitly set to undefined. The destructured or spread options object never carried a src.

Common situations: Destructuring a frontmatter variable that doesn't exist, conditional spreads that omit src, a typo (e.g. `source` instead of `src`), or a CMS payload missing the image field.

Related errors

• ExpectedImageOptions
• ExpectedNotESMImage
• ExpectedImage
• LocalImageUsedWrongly
• MissingImageDimension

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