Fix: Image Missing Required alt Property in Astro

Astro shows “Image missing required alt property” when an <Image /> or <Picture /> from astro:assets has no alt attribute. Astro makes alt required on purpose: “alt text is required to describe important images on the page.” Add a short description of what the image shows, or alt="" if the image is purely decorative.

Key Takeaways

• alt is required on <Image /> and <Picture />; Astro fails the build without it.
• Describe what the image communicates, not what it is (“Team at the 2026 offsite”, not “photo”).
• Use alt="" (empty, not missing) for decorative images, so screen readers skip them.
• For images from content collections or a CMS, make alt text a required field.

The fix

---
import { Image } from 'astro:assets';
import hero from '../assets/hero.jpg';
import divider from '../assets/divider.png';
---
<!-- Informative image -->
<Image src={hero} alt="Dashboard showing weekly signups rising" />

<!-- Decorative image -->
<Image src={divider} alt="" />

Writing useful alt text

• Say what matters in context. On a pricing page, “Screenshot of the billing settings” is more useful than “Laptop on a desk”.
• Keep it short. One sentence is usually enough. Don’t start with “Image of”; screen readers already announce it as an image.
• Don’t repeat nearby text. If a caption says the same thing, a shorter alt or alt="" avoids reading it twice.
• Text in images: if the image contains words that matter, put those words in the alt.
• Linked images: the alt describes where the link goes, for example “Komal Nakrani home”.

Alt text for content collections

When images come from frontmatter, require the alt text in the schema so the build catches missing values:

// src/content.config.ts
schema: ({ image }) => z.object({
  title: z.string(),
  cover: image(),
  coverAlt: z.string().min(1),
}),

<Image src={post.data.cover} alt={post.data.coverAlt} />

For a decorative cover, allow an empty string explicitly with z.string() and document when writers should leave it blank.

Markdown images

In Markdown, the alt text is the part in brackets: ![Team at the offsite](./team.jpg). Astro doesn’t enforce it there, so review Markdown images separately.

Why plain img tags don’t error

A plain <img> without alt won’t stop the build, but it’s still an accessibility problem, and screen readers may read out the file name instead. The accessibility basics in the Astro SEO checklist apply to every image.

For image sizing and formats, see responsive images in Astro and the Astro performance guide. The official error entry is in the Astro error reference.

FAQ

Can I disable the alt requirement in Astro?

No, and you shouldn’t. Pass alt="" for images that are decorative.

Is alt text good for SEO?

Search engines use alt text to understand images, and it helps image search. Its main purpose is accessibility; write it for people first.