withastro/astro · warning

⚠️ Astro could not optimize image "${transform.src}". Sharp

Error message

⚠️  Astro could not optimize image "${transform.src}". Sharp doesn't support this format. The image will be used unoptimized. Consider converting to WebP or placing in the public/ folder.

What it means

Sharp's toBuffer({ resolveWithObject: true }) threw during encode/decode inside Astro's image service, meaning Sharp cannot process this image (the source comment names animated AVIF sequences as the canonical case). Astro catches the failure, warns, and returns the original buffer unoptimized instead of crashing the build; once Sharp adds support for the format, the image is optimized automatically with no code changes.

Source

Thrown at packages/astro/src/assets/services/sharp.ts:253

		} else if (outputFormat === 'png') {
			result.png(encoderOptions as PngOptions | undefined);
		} else if (outputFormat === 'avif') {
			result.avif(encoderOptions as AvifOptions | undefined);
		} else if (outputFormat === 'jpeg' || outputFormat === 'jpg') {
			result.jpeg(encoderOptions as JpegOptions | undefined);
		} else {
			result.toFormat(outputFormat as keyof FormatEnum, encoderOptions);
		}

		let data: Uint8Array;
		let info: { format: string };
		try {
			({ data, info } = await result.toBuffer({ resolveWithObject: true }));
		} catch {
			// Sharp cannot decode this image (e.g. animated AVIF sequences).
			// Pass it through unmodified rather than crashing the build. When Sharp adds support for these
			// formats, the image will be optimized automatically without code changes.
			console.warn(
				`⚠️  Astro could not optimize image "${transform.src}". Sharp doesn't support this format. The image will be used unoptimized. Consider converting to WebP or placing in the public/ folder.`,
			);
			return { data: inputBuffer, format: bufferFormat as ImageOutputFormat };
		}

		// Sharp can sometimes return a SharedArrayBuffer when using WebAssembly.
		// SharedArrayBuffers need to be copied into an ArrayBuffer in order to be manipulated.
		const needsCopy = 'buffer' in data && data.buffer instanceof SharedArrayBuffer;

		return {
			data: needsCopy ? new Uint8Array(data) : data,
			format: info.format as ImageOutputFormat,
		};
	},
};

export default sharpService;

View on GitHub (pinned to 52e6c34790)

Solutions

1. Convert the image to WebP or another well-supported format, as the message suggests
2. Move the image into the public/ folder so Astro serves it without optimization
3. Reinstall/rebuild sharp so its native codecs match the platform (delete node_modules and reinstall, or pnpm rebuild sharp)
4. Verify the file is not corrupt: open it locally and re-export if needed

Example fix

# before: animated AVIF processed by the optimizer
src/components/Hero.astro -> <Image src={heroAvif} />

# after: bypass optimization for this asset
move src/assets/hero.avif -> public/hero.avif
<Image src="/hero.avif" />  becomes  <img src="/hero.avif" />

// Pre-flight: confirm Sharp can decode each asset before it reaches the optimizer
import sharp from 'sharp';
import { readdir } from 'node:fs/promises';
for (const file of await readdir('src/assets', { recursive: true })) {
  try { await sharp(`src/assets/${file}`).metadata(); }
  catch { console.warn(`Skipping unoptimizable asset: ${file} — move it to public/`); }
}

When it happens

Trigger: Optimizing an input Sharp's codec build cannot decode (animated AVIF/avis sequences are the documented example), a corrupt or truncated image file, or an encoder failure for the requested output format on that particular input.

Common situations: Animated AVIF exports from modern design tools; a sharp native binary mismatched to the OS or Node version after an upgrade; partially downloaded or corrupt images committed to the repo; exotic TIFF/RAW variants unsupported by the installed sharp build.

Related errors

• The current configuration does not support image optimizatio
• ⚠️ Astro expected an SVG for "${transform.src}" but the sou
• MissingSharp
• NoImageMetadata
• UnsupportedImageFormat

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