withastro/astro · error · AstroError

Invalid quality for picture

Error message

Invalid quality for picture "${options.src}"

What it means

The Netlify image service maps quality presets (low=25, mid=50, high=90, max=100) and then requires the resulting numeric quality to be between 1 and 100. A numeric quality outside that range throws this AstroError from validateOptions. Note the message says picture but it fires for Image/getImage too.

Solutions

1. Use an integer from 1 to 100, e.g. quality: 80
2. Use the named presets low, mid, high, or max
3. Convert 0-1 scale values by multiplying by 100 and rounding

Example fix

// before
<Image src={hero} quality={0.8} alt="hero" />
// after
<Image src={hero} quality={80} alt="hero" />

const QUALITY_NAMES: Record<string, number> = { low: 25, mid: 50, high: 90, max: 100 };
function normalizeQuality(q: number | string | undefined): number | undefined {
  const n = typeof q === 'string' ? QUALITY_NAMES[q] : q;
  return typeof n === 'number' && n >= 1 && n <= 100 ? Math.round(n) : undefined;
}
const quality = normalizeQuality(rawQuality);

function isValidNetlifyQuality(q: unknown): q is number | 'low' | 'mid' | 'high' | 'max' {
  if (typeof q === 'string') return q in { low: 1, mid: 1, high: 1, max: 1 };
  return typeof q === 'number' && q >= 1 && q <= 100;
}

When it happens

Trigger: Passing quality: 0, a negative number, a value above 100, or a 0-1 scale float like quality: 0.8 to Image/getImage with the Netlify adapter active.

Common situations: Quality values copied from tools that use a 0-1 scale (quality: 0.8) or a 0-100+ scale; passing quality: 0 intending lossless output.

Related errors

• Unsupported image format
• ⚠️ Astro expected an SVG for
• Configured image service is not a local service
• Configured image service is not a local service
• `context.next` is not implemented for serverless functions

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

Appendix: source

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

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

export default service;

View on GitHub (pinned to 52e6c34790)