withastro/astro · error · AstroError

ImageMissingAlt

ImageMissingAlt

Error message

Image missing "alt" property. "alt" text is required to describe important images on the page.

What it means

AstroError with code `ImageMissingAlt`, thrown by the `<Image>` component when the `alt` prop is `undefined` or `null`. Astro requires `alt` on every image for accessibility (screen readers and assistive tech); decorative images must explicitly pass `alt=""`. The error is thrown before any image transform happens, so it fails at render time of any `<Image>` call missing the prop.

Source

Thrown at packages/astro/components/Image.astro:15

---
import { getImage, imageConfig, type LocalImageProps, type RemoteImageProps } from 'astro:assets';
import type { UnresolvedImageTransform } from '../dist/assets/types.js';
import { AstroError, AstroErrorData } from '../dist/core/errors/index.js';
import type { HTMLAttributes } from '../types.js';

// The TypeScript diagnostic for JSX props uses the last member of the union to suggest props, so it would be better for
// LocalImageProps to be last. Unfortunately, when we do this the error messages that remote images get are complete nonsense
// Not 100% sure how to fix this, seems to be a TypeScript issue. Unfortunate.
type Props = LocalImageProps | RemoteImageProps;

const props = Astro.props;

if (props.alt === undefined || props.alt === null) {
	throw new AstroError(AstroErrorData.ImageMissingAlt);
}

// As a convenience, allow width and height to be string with a number in them, to match HTML's native `img`.
if (typeof props.width === 'string') {
	props.width = Number.parseInt(props.width);
}

if (typeof props.height === 'string') {
	props.height = Number.parseInt(props.height);
}

const layout = props.layout ?? imageConfig.layout ?? 'none';

if (layout !== 'none') {
	props.layout ??= imageConfig.layout;
	props.fit ??= imageConfig.objectFit ?? 'cover';
	props.position ??= imageConfig.objectPosition ?? 'center';
} else if (imageConfig.objectFit || imageConfig.objectPosition) {

View on GitHub (pinned to d081033d5f)

Solutions

1. Add a descriptive `alt` prop: `<Image src={img} alt="A red fox in the snow" />`.
2. For decorative images, pass an empty string explicitly: `<Image src={img} alt="" />`.
3. For dynamic/CMS content, default or guard the value: `alt={data.alt ?? ''}`.
4. Run `astro check` to catch missing-prop cases during development.

Example fix

// before
<Image src={hero} />

// after
<Image src={hero} alt="Hero illustration of the product" />

type ImageProps = { alt: string } & Record<string, unknown>;
function hasAlt(props: unknown): props is ImageProps {
  return typeof (props as any)?.alt === 'string';
}
// before rendering
if (!hasAlt(props)) props.alt = ''; // or throw a friendlier error

function hasAltProp(props: unknown): props is { alt: string } {
  return props != null && typeof (props as { alt?: unknown }).alt === 'string';
}

When it happens

Trigger: Calling `<Image src={...} />` without an `alt` prop; destructuring props and conditionally leaving `alt` unset; passing `alt={undefined}` or `alt={null}`; migrating from plain `<img>` and forgetting the prop.

Common situations: A developer drops in `<Image>` from a migration or template and omits `alt`; CMS-driven content where `alt` is optional and arrives undefined; conditional rendering that forgets the `alt` branch.

Related errors

• ImageMissingAlt
• Configured image service is not a local service
• Incorrect transform returned by `parseURL`
• Configured image service is not a local service
• Failed to parse image reference: ${imagePath}

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