withastro/astro · error · AstroError

NoImageMetadata

NoImageMetadata

Error message

Could not process image metadata for `${src}`.

What it means

`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.

Solutions

1. Verify the file: `file assets/banner.png` and open it in a viewer; confirm non-zero size
2. Re-export or re-download the asset into a supported raster format (png/jpeg/webp/avif/gif) or valid SVG
3. If it happens only in CI, compare checksums with your local copy to find the corrupting step (git lfs, artifact storage, proxy)

Example fix

```bash
# before
ls -l src/assets/banner.png   # 0 bytes

# after: restore the real file
git checkout -- src/assets/banner.png
ls -l src/assets/banner.png   # 48213 bytes
```

import { lookup } from 'image-size';

function assertImportableImage(data: Uint8Array, path: string): void {
  try {
    lookup(data);
  } catch {
    throw new Error(`${path} cannot be probed — replace or re-export the file`);
  }
}

try {
  const meta = await imageMetadata(data, src);
} catch (err) {
  if (err instanceof AstroError && err.code === 'NoImageMetadata') {
    // treat as opaque asset: use it via plain <img src> without the optimizer
    return;
  }
  throw err;
}

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• NoImageMetadata
• ImageNotFound
• NoImageMetadata
• ⚠️ Astro could not optimize image
• ⚠️ Astro expected an SVG for

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

Appendix: source

Thrown at packages/astro/src/assets/utils/metadata.ts:21

import { lookup as probe } from '../utils/vendor/image-size/lookup.js';

/**
 * Extracts image metadata such as dimensions, format, and orientation from the provided image data.
 *
 * @param {Uint8Array} data - The binary data of the image.
 * @param {string} [src] - The source path or URL of the image, used for error messages. Optional.
 * @return {Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>} A promise that resolves with the extracted metadata, excluding `src` and `fsPath`.
 * @throws {AstroError} Throws an error if the image metadata cannot be extracted.
 */
export async function imageMetadata(
	data: Uint8Array,
	src?: string,
): Promise<Omit<ImageMetadata, 'src' | 'fsPath'>> {
	let result;
	try {
		result = probe(data);
	} catch {
		throw new AstroError({
			...AstroErrorData.NoImageMetadata,
			message: AstroErrorData.NoImageMetadata.message(src),
		});
	}
	if (result.height == null || result.width == null || !result.type) {
		throw new AstroError({
			...AstroErrorData.NoImageMetadata,
			message: AstroErrorData.NoImageMetadata.message(src),
		});
	}

	const { width, height, type, orientation } = result;
	const isPortrait = (orientation || 0) >= 5;

	return {
		width: isPortrait ? height : width,
		height: isPortrait ? width : height,
		format: type as ImageInputFormat,

View on GitHub (pinned to 52e6c34790)