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}`).

Full serialized options received: `${fullOptions}`.

What it means

`getImage()` validates that `options.src` is defined before doing anything else (packages/astro/src/assets/internal.ts:59). An options object present but with `src` undefined (missing key, explicitly `undefined`, or a destructuring miss) throws `ExpectedImage` with the serialized options included.

Solutions

1. Ensure the options object contains a `src` that is either an ESM-imported image or a remote URL string.
2. Validate data before rendering: skip or substitute a placeholder when a record has no image.
3. Type the options parameter (`UnresolvedImageTransform`) so TypeScript flags missing `src` at compile time.

Example fix

// before — entry.image is undefined for some records
getImage({ src: entry.image, width: 800 });

// after — guard the data
if (!entry.image) return null;
getImage({ src: entry.image, width: 800 });

if (!('src' in options) || options.src === undefined) {
  throw new Error(`getImage options missing src: ${JSON.stringify(options)}`);
}

function hasDefinedSrc(value: unknown): value is { src: string | ImageMetadata } {
  return (
    typeof value === 'object' &&
    value !== null &&
    'src' in value &&
    (value as { src?: unknown }).src !== undefined
  );
}

When it happens

Trigger: `getImage({})`, `getImage({ width: 800 })`, or `src` computed from a lookup that returned undefined (e.g. a map keyed by slug where the slug is wrong).

Common situations: Looping over CMS/JSON data where some entries lack an image field; optional chaining that silently yields undefined; renamed props during refactors.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ExpectedImageOptions
• ExpectedNotESMImage
• IncompatibleDescriptorOptions
• RemoteImageNotAllowed
• ⚠️ Astro could not optimize image

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

Appendix: source

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

		return service;
	}

	return globalThis.astroAsset.imageService;
}

export async function getImage(
	options: UnresolvedImageTransform,
	imageConfig: AstroConfig['image'] & AstroAdapterClientConfig,
	logger: AstroRuntimeLogger,
): 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 e294953aa8)