withastro/astro · error · AstroError

NoImageMetadata

NoImageMetadata

Error message

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

What it means

Thrown by imageMetadata() when the vendored image-size probe() throws synchronously while parsing the raw bytes of an imported image. It is an AstroError (code NoImageMetadata) telling you Astro could not read any metadata from the bytes at all. The src argument is included in the message when supplied.

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 d081033d5f)

Solutions

1. Verify the file is non-empty and opens in an image viewer (`file src/assets/x.png`, check byte size).
2. Re-export or re-download the image from its source to repair corruption.
3. Confirm the format is supported by the vendored image-size probe (JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP, ICNS, ICO, SVG).
4. If you control the producer, regenerate the image and re-commit it.

Example fix

// before — `empty.png` is 0 bytes
import hero from './hero.png';

// after — replace with a valid image
import hero from './hero.png'; // where hero.png is a real, opens-in-editor image

import { readFileSync, statSync } from 'node:fs';
function isPlausibleImage(path: string): boolean {
  if (statSync(path).size === 0) return false;
  const b = readFileSync(path);
  // check common magic bytes
  const png = b.length >= 8 && b[0]===0x89 && b[1]===0x50 && b[2]===0x4e && b[3]===0x47;
  const jpg = b.length >= 3 && b[0]===0xff && b[1]===0xd8 && b[2]===0xff;
  const webp = b.length >= 12 && b.slice(0,4).toString()==='RIFF' && b.slice(8,12).toString()==='WEBP';
  const gif = b.length >= 6 && ['GIF87a','GIF89a'].includes(b.slice(0,6).toString());
  return png || jpg || webp || gif;
}

function hasImageMagic(b: Uint8Array): boolean {
  if (b.length < 4) return false;
  return (
    (b[0]===0x89 && b[1]===0x50 && b[2]===0x4e && b[3]===0x47) || // PNG
    (b[0]===0xff && b[1]===0xd8 && b[2]===0xff) ||                 // JPEG
    (b[0]===0x47 && b[1]===0x49 && b[2]===0x46) ||                 // GIF
    (b.slice(0,4).toString()==='RIFF')                              // WebP/AVIF container
  );
}

When it happens

Trigger: Importing or processing an image whose bytes cause the probe() lookup to throw: a zero-byte file, a truncated header, bytes that are not an image at all, or an unsupported/obscure format the probe cannot recognise. Reached via the assets metadata pipeline (vite-plugin-assets, getImage, content collections).

Common situations: An empty or partially-downloaded image checked into src/assets; a .png/.jpg whose magic bytes were corrupted by git-lfs/line-ending rewriting; a file mislabeled with an image extension; an HEIC/AVIF variant the vendored probe does not understand on an older Astro version.

Related errors

• NoImageMetadata
• SVG file does not contain an <svg> element
• FailedToFetchRemoteImageDimensions
• ImageNotFound
• No files found to copy

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