What causes "Unsupported image format "${options.format}"" in withastro/astro?

Use one of avif, jpg, png, webp

withastro/astro · error · AstroError

Unsupported image format

Error message

Unsupported image format "${options.format}"

What it means

The Netlify adapter installs an external image service that defers resizing to Netlify's /.netlify/images endpoint, which only outputs avif, jpg, png, and webp (SUPPORTED_FORMATS in image-service.ts). validateOptions runs for every Image/getImage call and throws this AstroError when options.format is outside that list.

Solutions

Use one of avif, jpg, png, webp
Spell JPEG as 'jpg', not 'jpeg'
For SVG, import/serve the SVG directly instead of transforming another image to SVG
Omit format to keep the source format when it is already supported

Example fix

// before
<Image src={hero} format="jpeg" width={828} alt="hero" />
// after
<Image src={hero} format="jpg" width={828} alt="hero" />

Defensive patterns

Strategy: validation

Validate before calling

const NETLIFY_FORMATS = ['avif', 'jpg', 'png', 'webp'] as const;
const format = NETLIFY_FORMATS.includes(options.format as any) ? options.format : undefined;
const img = await getImage({ ...options, format });

Type guard

const NETLIFY_FORMATS = ['avif', 'jpg', 'png', 'webp'] as const;
type NetlifyFormat = (typeof NETLIFY_FORMATS)[number];
function isNetlifyFormat(f: string): f is NetlifyFormat {
  return (NETLIFY_FORMATS as readonly string[]).includes(f);
}

Try / catch

import { AstroError } from 'astro/errors';
try {
  return await getImage(options);
} catch (err) {
  if (err instanceof AstroError && err.message.startsWith('Unsupported image format')) {
    return await getImage({ ...options, format: undefined });
  }
  throw err;
}

Prevention

Use 'jpg', never 'jpeg', when the Netlify adapter is active
Centralize image options in one helper so the format list is enforced in one place
Remember installing the adapter swaps the image service and its format support

When it happens

Trigger: Passing format: 'jpeg' (the list uses 'jpg'), or format: 'svg', 'gif', 'tiff' etc. to the Image component or getImage() while the Netlify adapter's image service is active.

Common situations: Migrating from Astro's default sharp service (which supports more output formats) to the Netlify adapter; typing 'jpeg' out of habit; attempting to convert a raster image into SVG.

Related errors

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

Appendix: source

Thrown at packages/integrations/netlify/src/image-service.ts:57

		if (options.format) query.set('fm', options.format);
		if (options.width) query.set('w', `${options.width}`);
		if (options.height) query.set('h', `${options.height}`);
		if (options.quality) query.set('q', `${options.quality}`);
		if (options.fit) {
			const netlifyFit = FIT_MAP[options.fit];
			if (netlifyFit) query.set('fit', netlifyFit);
		}

		return `/.netlify/images?${query}`;
	},
	getHTMLAttributes: baseService.getHTMLAttributes,
	getSrcSet: baseService.getSrcSet,
	validateOptions(options) {
		verifyOptions(options);

		if (options.format && !SUPPORTED_FORMATS.includes(options.format)) {
			throw new AstroError(
				`Unsupported image format "${options.format}"`,
				`Use one of ${SUPPORTED_FORMATS.join(', ')} instead.`,
			);
		}

		if (options.quality) {
			options.quality =
				typeof options.quality === 'string' ? QUALITY_NAMES[options.quality] : options.quality;
			if (options.quality < 1 || options.quality > 100) {
				throw new AstroError(
					`Invalid quality for picture "${options.src}"`,
					'Quality needs to be between 1 and 100.',
				);
			}
		}
		return options;
	},
};

View on GitHub (pinned to 52e6c34790)