axe-core "image-alt" images must have alternate text in CI

By Kaveh Alemi·Latchkey

axe-core rule image-alt found an <img> element with no accessible text alternative. WCAG 1.1.1 requires informative images to have an alt attribute; decorative images need alt="".

What this error means

axe reports "image-alt: Images must have alternate text" and points at an <img> whose alt attribute is missing entirely (not empty).

image-alt: Images must have alternate text (critical)
  Fix any of the following:
    Element does not have an alt attribute
    aria-label attribute does not exist or is empty
    Element has no title attribute
  <img src="/hero.png">

Common causes

The img was added without an alt attribute

A new image element shipped with src but no alt, so axe flags it as having no text alternative.

A decorative image was not marked as decorative

Purely decorative images still trip the rule when alt is absent; they need an explicit empty alt="", not a missing one.

How to fix it

Add descriptive alt text for informative images

1. Write concise alt text describing the image content or purpose.
2. For decorative images, set alt="" so screen readers skip them.
3. Re-run axe to confirm the rule passes.

<img src="/hero.png" alt="Team collaborating at a whiteboard" />
<img src="/divider.svg" alt="" />

Enforce it at lint time too

eslint-plugin-jsx-a11y catches missing alt during the lint gate so it never reaches the axe run.

// .eslintrc: "jsx-a11y/alt-text": "error"

How to prevent it

• Require alt text on every image in code review and lint.
• Mark decorative images with alt="" explicitly.
• Run axe across pages that render user-uploaded or CMS images.

Frequently asked questions

Related guides

References

• GitHub Actions documentation