{"record":{"id":"7f8d02fe728a8d44","repo":"withastro/astro","slug":"noimagemetadata","errorCode":"NoImageMetadata","errorMessage":"Could not process image metadata for `${transform.src}`.","messagePattern":"Could not process image metadata for `(.+?)`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/services/sharp.ts","lineNumber":171,"sourceCode":"\n\t\tconst bufferFormat = detector(inputBuffer);\n\t\t// Resolve the output format from the buffer when validateOptions deferred (ambiguous remote URL hit SSR, manually formed URLs etc)\n\t\tconst outputFormat = transform.format ?? resolveDefaultOutputFormat(bufferFormat);\n\n\t\t// TODO: Sharp has some support for SVGs, we could probably support this once Sharp is the default and only service.\n\t\tif (outputFormat === 'svg') {\n\t\t\tif (bufferFormat && bufferFormat !== 'svg') {\n\t\t\t\tlogger.warn(\n\t\t\t\t\t`Astro expected an SVG for \"${transform.src}\" but the source is ${bufferFormat}. Passing it through as ${bufferFormat} instead.`,\n\t\t\t\t);\n\t\t\t\treturn { data: inputBuffer, format: bufferFormat as ImageOutputFormat };\n\t\t\t}\n\t\t\treturn { data: inputBuffer, format: 'svg' };\n\t\t}\n\n\t\t// If we couldn't figure out the format, it's probably something weird we shouldn't try to process.\n\t\tif (!bufferFormat) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.NoImageMetadata,\n\t\t\t\tmessage: AstroErrorData.NoImageMetadata.message(transform.src),\n\t\t\t});\n\t\t}\n\n\t\tif (bufferFormat === 'svg' && !config.dangerouslyProcessSVG) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.UnsupportedImageFormat,\n\t\t\t\tmessage: `SVG image processing is disabled, but the source for \"${transform.src}\" is an SVG. Pass it through unchanged by setting \\`format=\"svg\"\\` on the component, or set \\`image.dangerouslyProcessSVG: true\\` to rasterize SVG sources.`,\n\t\t\t});\n\t\t}\n\n\t\tconst result = sharp(inputBuffer, {\n\t\t\tfailOn: 'none',\n\t\t\tpages: -1,\n\t\t\tlimitInputPixels: config.service.config.limitInputPixels,\n\t\t});\n","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/assets/services/sharp.ts#L153-L189","documentation":"Inside the Sharp service's `transform`, Astro probes the input buffer to learn its real format. If `sharp`'s metadata returns no recognizable format for the bytes (bufferFormat is undefined), Astro refuses to process the file and throws NoImageMetadata rather than guessing. It means the payload is corrupt, truncated, or a format the metadata probe cannot identify.","triggerScenarios":"Passing a truncated/corrupted image to `getImage()`; a file with an image extension whose actual bytes are something else (HTML error page saved as .png); an exotic format sharp cannot identify; zero-byte images; requesting non-svg processing of an unsupported binary.","commonSituations":"Images downloaded from a URL that actually returned HTML/JSON; files mangled by a bad git-lfs checkout or interrupted upload; CI artifacts corrupted by transfer; HEIC or ICO files renamed to .jpg.","solutions":["Open the file locally in an image viewer to confirm it is a valid, complete image; re-export it from an editor","Verify the bytes match the extension (e.g. `file hero.png`); re-download or re-commit the real image","If the file is a valid but unusual format, convert it to a supported one (png/jpeg/webp/avif/gif) before handing it to Astro"],"exampleFix":"```bash\n# before: file is actually HTML saved as .png\nfile public/hero.png\n# public/hero.png: HTML document text\n\n# after: replace with the real image\nfile public/hero.png\n# public/hero.png: PNG image data, 1200 x 630\n```","handlingStrategy":"validation","validationCode":"import { lookup } from 'image-size'; // or sniff magic bytes\n\nasync function assertProbeable(buffer: Uint8Array, name: string) {\n  try {\n    const dim = lookup(buffer);\n    if (!dim.width || !dim.height || !dim.type) throw new Error('no dims');\n  } catch {\n    throw new Error(`${name} is not a recognizable image — fix or exclude it`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  const result = await service.transform(inputBuffer, transform);\n} catch (err) {\n  if (err instanceof AstroError && err.code === 'NoImageMetadata') {\n    // copy the original through instead of transforming\n    return { data: inputBuffer, format: transform.format };\n  }\n  throw err;\n}","preventionTips":["Lint incoming assets in CI (file type + non-zero size) before build","Never rename non-image files to image extensions; re-export from a real editor"],"tags":["astro","images","sharp","corrupt-file","metadata"],"backgroundTag":"unreadable-image-metadata","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}