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

Thrown by verifyOptions() when an ESM-imported raster source (src.format !== 'svg') is requested to be output as svg. Converting a raster image (png/jpg/etc.) into a vector SVG is not supported, so the guard rejects it with UnsupportedImageConversion.

Source

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

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

Solutions

1. Remove format: 'svg' for raster sources.
2. Set format to a raster output (webp, avif, png, jpg) for raster sources.
3. Only use format: 'svg' with SVG sources for pass-through.
4. Audit shared image components for a hardcoded format attribute.

Example fix

// before
<Image src={photoJpg} format='svg' />

// after
<Image src={photoJpg} format='webp' />

function canOutputSvg(srcFormat: string, outputFormat: string): boolean {
  return !(srcFormat !== 'svg' && outputFormat === 'svg');
}

When it happens

Trigger: Passing format: 'svg' on an image whose imported src.format is not 'svg' (e.g. a jpg/png import with <Image format='svg' /> or getImage({ format: 'svg' })). The reverse (svg source rasterizing) is handled separately by sharp.

Common situations: Author hard-codes format='svg' across a set of images that includes rasters, or copies a config from an SVG usage into a raster pipeline.

Related errors

• UnsupportedImageFormat
• ExpectedImageOptions
• ExpectedImage
• ExpectedImage
• MissingImageDimension

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