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

The built-in `<Image />` component treats `alt` as mandatory and throws `ImageMissingAlt` at render time when the prop is `undefined` or `null`. This is an accessibility guard: every `<img>` needs alt text, so the component refuses to render without it. Empty-string alt (`alt=""`) is accepted and marks the image decorative.

Solutions

1. Add descriptive alt text: `<Image src={hero} alt="Team standing in front of the new office" />`
2. For decorative images pass an explicit empty string: `alt=""`
3. When alt comes from data, provide a fallback: `alt={post.altText ?? post.title}`

Example fix

// before
<Image src={hero} width={800} height={600} />

// after
<Image src={hero} width={800} height={600} alt="Product screenshot of the dashboard" />

function hasAlt(props: { alt?: string | null }): boolean {
  return props.alt != null;
}

When it happens

Trigger: Rendering `<Image src={...} width={...} height={...} />` with no `alt`; passing `alt={undefined}` because the variable powering it is not set (e.g. `alt={post.altText}` where altText is missing from CMS data); spreading props from an object without alt.

Common situations: CMS entries lacking an alt field that flows straight into the component; refactoring from plain `<img>` (where missing alt only warns) to `<Image>`; conditional props where alt is accidentally dropped.

Related errors

• ImageMissingAlt
• FontFamilyNotFound
• InvalidComponentArgs
• Missing `width` parameter for remote image
• [transitions]: all view transition animations, including…

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

Appendix: 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 52e6c34790)