{"record":{"id":"8165b7f1081f4a3b","repo":"withastro/astro","slug":"noimagemetadata-8165b7","errorCode":"NoImageMetadata","errorMessage":"Could not process image metadata for `${src}`.","messagePattern":"Could not process image metadata for `(.+?)`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/utils/metadata.ts","lineNumber":21,"sourceCode":"import { lookup as probe } from '../utils/vendor/image-size/lookup.js';\n\n/**\n * Extracts image metadata such as dimensions, format, and orientation from the provided image data.\n *\n * @param {Uint8Array} data - The binary data of the image.\n * @param {string} [src] - The source path or URL of the image, used for error messages. Optional.\n * @return {Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>} A promise that resolves with the extracted metadata, excluding `src` and `fsPath`.\n * @throws {AstroError} Throws an error if the image metadata cannot be extracted.\n */\nexport async function imageMetadata(\n\tdata: Uint8Array,\n\tsrc?: string,\n): Promise<Omit<ImageMetadata, 'src' | 'fsPath'>> {\n\tlet result;\n\ttry {\n\t\tresult = probe(data);\n\t} catch {\n\t\tthrow new AstroError({\n\t\t\t...AstroErrorData.NoImageMetadata,\n\t\t\tmessage: AstroErrorData.NoImageMetadata.message(src),\n\t\t});\n\t}\n\tif (result.height == null || result.width == null || !result.type) {\n\t\tthrow new AstroError({\n\t\t\t...AstroErrorData.NoImageMetadata,\n\t\t\tmessage: AstroErrorData.NoImageMetadata.message(src),\n\t\t});\n\t}\n\n\tconst { width, height, type, orientation } = result;\n\tconst isPortrait = (orientation || 0) >= 5;\n\n\treturn {\n\t\twidth: isPortrait ? height : width,\n\t\theight: isPortrait ? width : height,\n\t\tformat: type as ImageInputFormat,","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/assets/utils/metadata.ts#L3-L39","documentation":"`imageMetadata()` is what Astro uses when you import an image (and when probing buffers) to read width/height/format via the vendored image-size `lookup` probe. If `probe(data)` itself throws — the bytes are not recognizable as any known image format — Astro throws NoImageMetadata naming the file. Distinguish this from the line-27 variant: here the probe crashed outright, meaning the data is not a decodable image at all.","triggerScenarios":"`import img from './assets/banner.png'` where banner.png is corrupt, empty, or not an image; a build tool or git filter corrupting imported assets; a remote image whose bytes are an HTML error page.","commonSituations":"Zero-byte images after a failed checkout/transfer; files with doubled extensions or wrong bytes; images in formats image-size cannot recognize (e.g. some HEIC/ICO variants); assets mutated by a preprocessing plugin.","solutions":["Verify the file: `file assets/banner.png` and open it in a viewer; confirm non-zero size","Re-export or re-download the asset into a supported raster format (png/jpeg/webp/avif/gif) or valid SVG","If it happens only in CI, compare checksums with your local copy to find the corrupting step (git lfs, artifact storage, proxy)"],"exampleFix":"```bash\n# before\nls -l src/assets/banner.png   # 0 bytes\n\n# after: restore the real file\ngit checkout -- src/assets/banner.png\nls -l src/assets/banner.png   # 48213 bytes\n```","handlingStrategy":"try-catch","validationCode":"import { lookup } from 'image-size';\n\nfunction assertImportableImage(data: Uint8Array, path: string): void {\n  try {\n    lookup(data);\n  } catch {\n    throw new Error(`${path} cannot be probed — replace or re-export the file`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  const meta = await imageMetadata(data, src);\n} catch (err) {\n  if (err instanceof AstroError && err.code === 'NoImageMetadata') {\n    // treat as opaque asset: use it via plain <img src> without the optimizer\n    return;\n  }\n  throw err;\n}","preventionTips":["Validate assets with a probe step in CI before astro build","Track images with git-lfs carefully — verify checkout integrity"],"tags":["astro","images","import","corrupt-file","metadata"],"backgroundTag":"unreadable-image-metadata","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}