withastro/astro · error · AstroError

ExpectedImageOptions

ExpectedImageOptions

Error message

Expected `getImage()` parameter to be an object. Received `${options}`.

What it means

`getImage(options, imageConfig)` (packages/astro/src/assets/internal.ts:53) requires its first argument to be an options object. If it receives a primitive, null, or undefined (`typeof options !== 'object'`), it throws `ExpectedImageOptions` with the received value serialized into the message.

Solutions

1. Pass an options object: `getImage({ src, width, height })`.
2. If options come from dynamic data, guard with `if (!options || typeof options !== 'object')` and fail with your own message.
3. Check for typos like `getImage(src)` where a variable shadows the intended options object.

Example fix

// before
const img = await getImage(heroImagePath);

// after
const img = await getImage({ src: heroImagePath, width: 800, height: 600 });

if (!options || typeof options !== 'object') {
  throw new Error(`getImage expected an options object, got ${typeof options}`);
}

import type { UnresolvedImageTransform } from 'astro';

function isImageOptions(value: unknown): value is UnresolvedImageTransform {
  return typeof value === 'object' && value !== null;
}

When it happens

Trigger: Calling `getImage('hero.png')`, `getImage(undefined)` (e.g. a variable that failed to initialize), or passing the output of a function that returns a string instead of an options object.

Common situations: Refactoring from string-based helpers; data-driven rendering where a map lookup returns undefined; passing already-resolved URL strings from an older Astro snippet.

Related errors

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

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

Appendix: source

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

			error.cause = e;
			throw error;
		});

		if (!globalThis.astroAsset) globalThis.astroAsset = {};
		globalThis.astroAsset.imageService = service;
		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);
	}

View on GitHub (pinned to e294953aa8)