withastro/astro · error · AstroError

UnsupportedImageFormat

UnsupportedImageFormat

Error message

Received unsupported format `${format}` from `${imagePath}`. Currently only ${supportedFormats.join(', ')} are supported by our image services.

What it means

Thrown by verifyOptions() for ESM-imported images when the imported asset's format is not in VALID_SUPPORTED_FORMATS (jpeg, jpg, png, tiff, webp, gif, svg, avif). The format comes from the import metadata, so this rejects imports of unsupported image types like .bmp, .ico, .heic.

Source

Thrown at packages/astro/src/assets/services/service.ts:188

		// For remote images, width and height are explicitly required as we can't infer them from the file
		let missingDimension: 'width' | 'height' | 'both' | undefined;
		if (!options.width && !options.height) {
			missingDimension = 'both';
		} else if (!options.width && options.height) {
			missingDimension = 'width';
		} else if (options.width && !options.height) {
			missingDimension = 'height';
		}

		if (missingDimension) {
			throw new AstroError({
				...AstroErrorData.MissingImageDimension,
				message: AstroErrorData.MissingImageDimension.message(missingDimension, options.src),
			});
		}
	} else {
		if (!VALID_SUPPORTED_FORMATS.includes(options.src.format as any)) {
			throw new AstroError({
				...AstroErrorData.UnsupportedImageFormat,
				message: AstroErrorData.UnsupportedImageFormat.message(
					options.src.format,
					options.src.src,
					VALID_SUPPORTED_FORMATS,
				),
			});
		}

		if (options.widths && options.densities) {
			throw new AstroError(AstroErrorData.IncompatibleDescriptorOptions);
		}

		if (options.src.format !== 'svg' && options.format === 'svg') {
			throw new AstroError(AstroErrorData.UnsupportedImageConversion);
		}
	}
}

View on GitHub (pinned to d081033d5f)

Solutions

1. Convert the source image to a supported format (png, jpg, webp, avif, gif, tiff, or svg).
2. For static pass-through of vector content, use svg.
3. Re-export the asset in a supported container if the source is unusual.
4. Confirm the import pipeline correctly detected format; if undefined, the file may be corrupt.

Example fix

// before
import logo from './logo.ico';

// after - convert logo.ico to logo.svg or logo.png first
import logo from './logo.svg';

const SUPPORTED = new Set(['jpeg','jpg','png','tiff','webp','gif','svg','avif']);
function isSupportedFormat(fmt: string): boolean { return SUPPORTED.has(fmt.toLowerCase()); }

type SupportedFormat = 'jpeg'|'jpg'|'png'|'tiff'|'webp'|'gif'|'svg'|'avif';
function isSupportedFormat(fmt: string): fmt is SupportedFormat {
  return new Set(['jpeg','jpg','png','tiff','webp','gif','svg','avif']).has(fmt.toLowerCase());
}

When it happens

Trigger: Importing an ESM asset whose format (options.src.format) is not in the supported list and then passing it to Image/getImage. The offending format and the asset's src, plus the supported list, are interpolated into the message.

Common situations: Author imports a .bmp, .ico, .heif, or .raw file as an image asset; or an asset's detected format is undefined/unrecognized by the import pipeline.

Related errors

• UnsupportedImageConversion
• ExpectedImageOptions
• ExpectedImage
• ExpectedNotESMImage
• ExpectedImage

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