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

For ESM-imported images, `verifyOptions()` checks the import's declared `format` against the formats the image services can process — `jpeg, jpg, png, tiff, webp, gif, svg, avif` (packages/astro/src/assets/consts.ts:25) — and throws `UnsupportedImageFormat` listing the supported set (packages/astro/src/assets/services/service.ts:188).

Solutions

1. Convert the file to a supported format (png/webp for bitmaps, svg for vector) and re-import.
2. For `.ico` favicons referenced verbatim, keep them in `public/` and link them with a plain `<link rel="icon">` instead of the image pipeline.
3. Automate a pre-commit/build check that flags unsupported extensions in `src/assets`.

Example fix

# before
import icon from './favicon.ico';

# after — convert once, then import
convert favicon.ico favicon.png

import { extname } from 'node:path';
const VALID = ['jpeg', 'jpg', 'png', 'tiff', 'webp', 'gif', 'svg', 'avif'];
// CI script: scan imported image assets for unsupported extensions
for (const file of imageFiles) {
  const ext = extname(file).slice(1).toLowerCase();
  if (!VALID.includes(ext)) {
    throw new Error(`Unsupported image format .${ext}: ${file}`);
  }
}

const SUPPORTED_IMAGE_EXTENSIONS = ['jpeg', 'jpg', 'png', 'tiff', 'webp', 'gif', 'svg', 'avif'];
const isSupportedImageFile = (path: string): boolean =>
  SUPPORTED_IMAGE_EXTENSIONS.includes(path.split('.').pop()?.toLowerCase() ?? '');

When it happens

Trigger: Importing an `.ico`, `.bmp`, `.heic`, or other exotic file through `import x from './icon.ico'` and passing it to `<Image>`/`getImage()`.

Common situations: Favicons and legacy assets in `.ico`/`.bmp`; designer handoffs with `.heic`/`.tiff` (tiff is supported, heic is not); assets shared with non-web projects.

Related errors

• ExpectedNotESMImage
• LocalImageUsedWrongly
• ⚠️ Astro could not optimize image
• ⚠️ Astro expected an SVG for
• Configured image service is not a local service

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

Appendix: source

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

		// 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 e294953aa8)