withastro/astro · error · AstroError

UnsupportedImageConversion

UnsupportedImageConversion

Error message

Converting between vector (such as SVGs) and raster (such as PNGs and JPEGs) images is not currently supported.

What it means

Astro's base image service validates transform options in `getValidationOptions` and throws UnsupportedImageConversion when you request SVG output from a non-SVG source. Astro can rasterize SVGs but cannot turn a raster image (PNG, JPEG, WebP...) into a vector SVG. The check is `options.src.format !== 'svg' && options.format === 'svg'` in packages/astro/src/assets/services/service.ts.

Solutions

1. Remove `format: 'svg'` from the getImage()/Image call and let Astro pick a supported raster output (webp/avif/png/jpeg), or omit format entirely
2. If the source really is vector, point `src` at the actual .svg file (or an `import` of it) so the detected source format is svg
3. If you want the original bytes untouched, use `format="svg"` only for SVG sources, or reference the file directly without the Image component

Example fix

// before
<Image src={heroPng} format="svg" alt="Hero" />

// after
<Image src={heroPng} format="webp" alt="Hero" />

import type { ImageInputFormat, ImageOutputFormat } from 'astro/assets';

const RASTER: ReadonlySet<string> = new Set(['png', 'jpg', 'jpeg', 'webp', 'avif', 'gif']);

// run before getImage()/Image
function assertConversionSupported(srcFormat: ImageInputFormat, outFormat?: ImageOutputFormat) {
  if (outFormat === 'svg' && srcFormat !== 'svg') {
    throw new Error(`Cannot convert ${srcFormat} to svg; pick a raster output format or drop format.`);
  }
}

function isSupportedConversion(
  srcFormat: string,
  outFormat: string | undefined,
): outFormat is 'svg' | undefined {
  return outFormat !== 'svg' || srcFormat === 'svg';
}

try {
  const img = await getImage(options);
} catch (err) {
  if (err instanceof AstroError && err.code === 'UnsupportedImageConversion') {
    // strip the svg output format and retry
    const { format: _f, ...rest } = options;
    return getImage(rest);
  }
  throw err;
}

When it happens

Trigger: Calling `getImage({ src: pngImage, format: 'svg' })`, or rendering `<Image src={jpg} format="svg" />` / `<Picture formats={["svg"]}>` with a raster source. Only fires when the detected source format is not 'svg' while the requested output format is 'svg'.

Common situations: Trying to 'convert' a photo to SVG to save bandwidth; copying a `format` prop from an SVG example onto a raster image; UI presets that pass a fixed format list including svg; passing format="svg" thinking it means 'serve original'.

Related errors

• ⚠️ Astro expected an SVG for
• UnsupportedImageFormat
• ⚠️ Astro could not optimize image
• CannotOptimizeSvg
• ExpectedImage

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

Appendix: source

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

		}
	} 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);
		}
	}
}

/**
 * Basic local service using the included `_image` endpoint.
 * This service intentionally does not implement `transform`.
 *
 * Example usage:
 * ```ts
 * const service = {
 *  getURL: baseService.getURL,
 *  parseURL: baseService.parseURL,
 *  getHTMLAttributes: baseService.getHTMLAttributes,
 *  async transform(inputBuffer, transformOptions) {...}
 * }
 * ```
 *

View on GitHub (pinned to e294953aa8)