{"record":{"id":"a58702d490ad41fe","repo":"withastro/astro","slug":"astro-could-not-optimize-image-transform-sr","errorCode":null,"errorMessage":"⚠️  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.","messagePattern":"⚠️  Astro could not optimize image \"(.+?)\"\\. Sharp doesn't support this format\\. The image will be used unoptimized\\. Consider converting to WebP or placing in the public/ folder\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/astro/src/assets/services/sharp.ts","lineNumber":253,"sourceCode":"\t\t} else if (outputFormat === 'png') {\n\t\t\tresult.png(encoderOptions as PngOptions | undefined);\n\t\t} else if (outputFormat === 'avif') {\n\t\t\tresult.avif(encoderOptions as AvifOptions | undefined);\n\t\t} else if (outputFormat === 'jpeg' || outputFormat === 'jpg') {\n\t\t\tresult.jpeg(encoderOptions as JpegOptions | undefined);\n\t\t} else {\n\t\t\tresult.toFormat(outputFormat as keyof FormatEnum, encoderOptions);\n\t\t}\n\n\t\tlet data: Uint8Array;\n\t\tlet info: { format: string };\n\t\ttry {\n\t\t\t({ data, info } = await result.toBuffer({ resolveWithObject: true }));\n\t\t} catch {\n\t\t\t// Sharp cannot decode this image (e.g. animated AVIF sequences).\n\t\t\t// Pass it through unmodified rather than crashing the build. When Sharp adds support for these\n\t\t\t// formats, the image will be optimized automatically without code changes.\n\t\t\tconsole.warn(\n\t\t\t\t`⚠️  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.`,\n\t\t\t);\n\t\t\treturn { data: inputBuffer, format: bufferFormat as ImageOutputFormat };\n\t\t}\n\n\t\t// Sharp can sometimes return a SharedArrayBuffer when using WebAssembly.\n\t\t// SharedArrayBuffers need to be copied into an ArrayBuffer in order to be manipulated.\n\t\tconst needsCopy = 'buffer' in data && data.buffer instanceof SharedArrayBuffer;\n\n\t\treturn {\n\t\t\tdata: needsCopy ? new Uint8Array(data) : data,\n\t\t\tformat: info.format as ImageOutputFormat,\n\t\t};\n\t},\n};\n\nexport default sharpService;\n","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/assets/services/sharp.ts#L235-L271","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Convert the image to WebP or another well-supported format, as the message suggests","Move the image into the public/ folder so Astro serves it without optimization","Reinstall/rebuild sharp so its native codecs match the platform (delete node_modules and reinstall, or pnpm rebuild sharp)","Verify the file is not corrupt: open it locally and re-export if needed"],"exampleFix":"# before: animated AVIF processed by the optimizer\nsrc/components/Hero.astro -> <Image src={heroAvif} />\n\n# after: bypass optimization for this asset\nmove src/assets/hero.avif -> public/hero.avif\n<Image src=\"/hero.avif\" />  becomes  <img src=\"/hero.avif\" />","handlingStrategy":"validation","validationCode":"// Pre-flight: confirm Sharp can decode each asset before it reaches the optimizer\nimport sharp from 'sharp';\nimport { readdir } from 'node:fs/promises';\nfor (const file of await readdir('src/assets', { recursive: true })) {\n  try { await sharp(`src/assets/${file}`).metadata(); }\n  catch { console.warn(`Skipping unoptimizable asset: ${file} — move it to public/`); }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid animated AVIF in assets handled by the image service; use WebP or public/","After Node/OS upgrades, reinstall so the sharp native binary matches the platform","Keep a small sharp metadata smoke-test in CI over committed images to catch corrupt/exotic files"],"tags":["astro","images","sharp","avif","codec","optimization","passthrough"],"backgroundTag":"unsupported-image-codec","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}