withastro/astro · error · AstroError

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

Error message

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

What it means

After mapping named qualities (`low`/`mid`/`high`/`max` → 25/50/90/100), the Netlify service checks numeric quality is within `[1,100]`. Anything outside — including `0`, negative numbers, or values above 100 — throws `AstroError` naming the picture source. This mirrors Netlify Image CDN's valid quality range.

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

Solutions

1. Set `quality` to an integer between 1 and 100 inclusive.
2. Use a named quality: `low`, `mid`, `high`, or `max`.
3. If passing a 0–1 float, multiply by 100 first.
4. Omit `quality` to use the service default.

Example fix

// before
await getImage({ src, quality: 0.8 });

// after
await getImage({ src, quality: 80 });

function clampNetlifyQuality(q: number | string | undefined): number | undefined {
  if (q == null) return undefined;
  const n = typeof q === 'string' ? ({ low: 25, mid: 50, high: 90, max: 100 } as Record<string, number>)[q] ?? Number(q) : q;
  if (!Number.isFinite(n) || n < 1 || n > 100) {
    throw new Error('Netlify image quality must be an integer between 1 and 100');
  }
  return n;
}

function isNetlifyQuality(q: unknown): boolean {
  const n = typeof q === 'number' ? q : NaN;
  return Number.isInteger(n) && n >= 1 && n <= 100;
}

When it happens

Trigger: Passing `quality: 0`, `quality: 150`, a negative number, or a numeric string outside 1–100 to `getImage`/`getPicture` under the Netlify service. A named quality that resolves (via `QUALITY_NAMES`) to an out-of-range number (not possible with defaults, but a custom override could).

Common situations: Copy-pasting a sharp config that allows `quality: 0`. Treating quality as a 0–1 float. Migrating from another service with a different range.

Related errors

• Unsupported image format "${options.format}"
• ExpectedImageOptions
• ExpectedImage
• ExpectedImage
• MissingImageDimension

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