withastro/astro · error · AstroError

Unsupported image format "${options.format}"

Error message

Unsupported image format "${options.format}"

What it means

The Netlify image service's `validateOptions` rejects any `format` not in `['avif','jpg','png','webp']`. This is narrower than Astro's base set (no `gif`, `svg` output, etc.) because Netlify's Image CDN only supports those four output formats. It throws `AstroError` with a hint listing the allowed formats.

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

Solutions

1. Use one of: `avif`, `jpg`, `png`, `webp`.
2. If you need `jpeg`, spell it as `jpg`.
3. Switch the image service back to `'astro/assets/services/sharp'` or `squoosh'` if you require other formats.
4. Remove the explicit `format` to let the service pick a supported default.

Example fix

// before
import { getImage } from 'astro:assets';
await getImage({ src, format: 'jpeg' });

// after
await getImage({ src, format: 'jpg' });

const NETLIFY_FORMATS = ['avif', 'jpg', 'png', 'webp'] as const;
function isNetlifyFormat(f: string): f is typeof NETLIFY_FORMATS[number] {
  return (NETLIFY_FORMATS as readonly string[]).includes(f);
}
if (options.format === 'jpeg') options.format = 'jpg';
if (options.format && !isNetlifyFormat(options.format)) {
  throw new Error(`Unsupported format; use one of ${NETLIFY_FORMATS.join(', ')}`);
}

function isSupportedFormat(f: unknown): f is 'avif' | 'jpg' | 'png' | 'webp' {
  return f === 'avif' || f === 'jpg' || f === 'png' || f === 'webp';
}

When it happens

Trigger: Configuring an image/picture with `format: 'gif'`, `'jpeg'` (note: it's `jpg` not `jpeg`), `'svg'` output, or any unsupported value while the Netlify adapter is active. Setting `image.format` globally in config to something Netlify rejects.

Common situations: Migrating from sharp/squoosh default service to Netlify and keeping a previously-valid format. Using `'jpeg'` instead of `'jpg'`. Configuring a picture element with an explicit unsupported format.

Related errors

• Invalid quality for picture "${options.src}"
• CannotOptimizeSvg
• RemoteImageNotAllowed
• ImageNotFound
• Could not resolve image ${JSON.stringify(node.attributes.src

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