withastro/astro · error · AstroError

ExpectedImageOptions

ExpectedImageOptions

Error message

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

What it means

Thrown by getImage() when the options argument is not a non-null object. The very first guard checks `!options || typeof options !== 'object'`; passing undefined, null, a primitive (string/number), or anything non-object yields ExpectedImageOptions with the JSON-serialized received value.

Source

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

			const error = new AstroError(AstroErrorData.InvalidImageService);
			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,
): 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 d081033d5f)

Solutions

1. Pass an options object: getImage({ src: ..., width: ..., height: ... }).
2. Wrap the call in a guard if options may be undefined: if (options) getImage(options).
3. Check that the variable feeding getImage is actually assigned before the call.
4. If using a helper, ensure it returns an object, not null/undefined.

Example fix

// before
getImage('/img/photo.jpg')

// after
getImage({ src: '/img/photo.jpg', width: 800, height: 600 })

function isImageOptions(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

function isImageOptions(v: unknown): v is { src: unknown } {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

When it happens

Trigger: Calling getImage(options, imageConfig) where options is undefined, null, a string, a number, a boolean, or an array-like that is not a plain object. Note: arrays technically pass typeof 'object', but a missing `src` would then surface a different error.

Common situations: Calling getImage() with no arguments, passing a raw string path instead of { src: '...' }, spreading undefined into the call, or a variable that was never assigned.

Related errors

• ExpectedImage
• ExpectedNotESMImage
• ExpectedImage
• LocalImageUsedWrongly
• MissingImageDimension

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