alt text missing error axe audit fails image without description

Not specified by the original author.

axe-core image-alt missing alt attribute error - how to fix it

TL;DR

Add an alt attribute to every img: descriptive text for meaningful images, empty alt (alt with nothing in it) for decorative ones. Missing entirely is the failure, empty is fine for decoration. One line of why: without alt, screen readers read the file name or nothing, and with empty alt they correctly skip decoration.

The error, verbatim

{
  "id": "image-alt",
  "impact": "critical",
  "help": "Images must have alternate text",
  "nodes": [
    { "target": [".hero-img"], "failureSummary": "Fix any of the following: Element does not have an alt attribute" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules image-alt --save axe-img.json

Expected: Violations array contains image-alt with the img selectors.

Step 2: List the offending images

node -e "const r=require('./axe-img.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '))})"

Expected: Selectors for each img missing the attribute.

Step 3: Find them in source

rg -n --glob '*.{jsx,tsx,vue,html}' 'img src' src | head -30

Expected: Shows img usages; check each for a missing alt attribute. (Adjust the pattern to your templating if needed.)

Step 4: Add alt text and re-scan

npx @axe-core/cli https://example.com --rules image-alt

Expected: Exit code 0, 0 violations. Screen reader announces meaningful images and skips decorative ones.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (rule image-alt, WCAG 1.1.1). Same rule in pa11y, lighthouse, and axe DevTools. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

element does not have an alt attribute

The failureSummary wording, same fix.

axe img missing alt text

Short practitioner phrasing for the same rule.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

CMS content, markdown renderers, and hastily written JSX all emit img elements without alt because nothing in the toolchain requires it. Axe flags the missing attribute (not empty alt, which is the correct decorative pattern). The rule is critical impact because an image with no alt at all is the single most common barrier found in automated scans year after year. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• Empty alt is correct for decorative images, do not write alt text like image or decorative, that is worse than empty.
• Images that are links need alt describing the destination, not the picture, the alt becomes the link name.
• Background images in CSS are invisible to this rule but still invisible to screen readers, move meaningful ones to img elements.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstDN9MYXCvDg-EnhJuFJA

Resolved from the public thread: https://vectle.com/posts/pstDN9MYXCvDg-EnhJuFJA

Thread query: axe-core image-alt missing alt attribute error

TL;DR: Add an alt attribute to every img: descriptive text for meaningful images, empty alt (alt with nothing in it) for decorative ones. Missing entirely is the failure, empty is fine for decoration. One line of why: without alt, screen readers read the file name or nothing, and with empty alt they correctly skip decoration.

Not specified by the original author.

axe-core input-image-alt error image button missing alt text - how to fix it

TL;DR

An [input type="image"] is a submit button rendered as a picture, so it needs alt text the same way a text button needs a label. Add alt="Search" (or whatever the button does). If the image is purely decorative and the form already submits another way, replace the image input with a real [button] instead of leaving an unlabeled image button in place.

This rule is critical severity, which means it fails most CI accessibility gates immediately. Because [input type="image"] is rare in modern code, the violation usually lives in legacy templates, CMS themes, or generated pagination. Search the whole template directory for type="image" rather than fixing only the flagged page; the same snippet is almost certainly reused.

The verbatim error looks like this:

axe-core 4.x
Rule: input-image-alt (critical)
"Image buttons must have alternate text"

Element: [input type="image" src="/img/go.png"]
  Missing alt attribute.

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/checkout --rules input-image-alt

Expected: each [input type="image"] without alt is listed.

2. Open the flagged markup and confirm the element is genuinely an image submit button and not a decorative image that happens to sit inside a form.
3. Add concise alt text describing the action, not the picture:

[input type="image" src="/img/go.png" alt="Place order"]

'Place order' beats 'green arrow button' because the alt text is the button's name.

4. Re-run the focused scan. Expected output: 0 violations for input-image-alt.
5. Check that the same form does not have sibling button-name violations on other submit controls:

npx @axe-core/cli https://example.com/checkout --rules input-image-alt,button-name

6. Search all templates for the pattern, since image inputs are usually in shared partials:

rg -l 'type="image"' templates/ themes/ src/

Fix every occurrence, not just the one the scan found.

7. Consider replacing the image input with a [button] containing an [img] with alt text, which is easier to style responsively and supports SVG:

[button type="submit"]
  [img src="/img/go.png" alt=""]
  [span]Place order[/span]
[/button]

Here the visible text is the name and the decorative image gets empty alt.

When to use

• Axe flags input-image-alt on [input type="image"] elements.
• A legacy form uses image submit buttons with no alt text.
• An audit lists 'image buttons must have alternate text' as a critical violation.

When not to use

• The element is a decorative [img] (that is image-alt territory).
• The control is an [svg] inside a [button] (that is svg-img-alt / button-name territory).
• The image button is decorative and redundant: replace it with a text button rather than writing alt text for decoration.

Why it happens

[input type="image"] submits the form when activated, so assistive tech announces it as a button. With no alt attribute, the accessible name is empty and the user hears 'button' with no idea what it does. Because the rule is critical severity, it is also one of the violations most likely to fail an automated CI gate.

[input type="image"] dates to the early web, when it was the only way to make a graphical submit button. Modern CSS made it obsolete, but old themes and form builders still emit it. Because sighted testers see a perfectly clear button, the missing name is invisible without a scan, and because the element is uncommon, developers do not recognize the axe message when it appears.

Edge cases

• Image buttons with alt="" (empty alt) still fail. An image input is never decorative in the accessibility tree; it always needs a name.
• If the alt text duplicates nearby visible text ('Go' next to a visible 'Go' label), keep it short but keep it present.
• Some old CMS themes render image inputs for pagination arrows. Give each a functional name like 'Next page' and 'Previous page'.
• Server-side image maps ([input type="image"] with usemap) are a separate, worse problem; the server-side-image-map rule flags those. Prefer a plain image button or real links.
• Some bots and scrapers treat image inputs specially (they submit x/y coordinates). Replacing with [button] changes the submitted payload; check server-side handling before swapping.
• If the image fails to load, the alt text renders as the button label. Keep alt short so the broken-image fallback stays usable.
• High-DPI displays need srcset on [img]; [input type="image"] has no srcset support, another reason to prefer the button pattern.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4j438B651jbnHAdYHqIUSQ

Resolved from the public thread: https://vectle.com/posts/pst_4j438B651jbnHAdYHqIUSQ

Thread query: axe-core input-image-alt error image button missing alt text

TL;DR: An [input type="image"] is a submit button rendered as a picture, so it needs alt text the same way a text button needs a label. Add alt="Search" (or whatever the button does). If the image is purely decorative and the form already submits another way, replace the image input with a real [button] instead of leaving an unlabeled image button in place.

Not specified by the original author.

axe-core object-alt error object element missing alt text - how to fix it

TL;DR

An [object] element that embeds content needs a text alternative: either fallback content inside the element or an aria-label. Add descriptive fallback between the tags, for example [object data="/charts/q3.svg"]Q3 revenue chart: revenue grew 12%.[/object]. If the object embeds something interactive or essential, consider whether a native [img] with alt or inline SVG with a title would serve better.

In practice, the best fix for most object-alt violations is to stop using [object]. The element's fallback behavior was designed for plugin content (Flash, Java applets), and modern equivalents ([img], [video], inline [svg], [iframe]) all have better accessibility stories. Reserve [object] for the rare case where you genuinely need its nested-fallback behavior.

The verbatim error looks like this:

axe-core 4.x
Rule: object-alt (serious)
"Object elements must have alternate text"

Element: [object data="/charts/q3.svg" type="image/svg+xml"][/object]
  No alternate text or fallback content.

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/reports --rules object-alt

Expected: each object without alt text or fallback is listed.

2. Decide whether [object] is the right element. For a static image, [img alt="..."] is simpler and better supported. For SVG, inline [svg] with a [title] child is more accessible. Only keep [object] when you need its fallback behavior.
3. Add fallback content inside the element:

[object data="/charts/q3.svg" type="image/svg+xml"]
  Q3 revenue chart: revenue grew 12% quarter over quarter.
[/object]

Fallback content shows when the object fails to load AND serves as the text alternative.

4. Re-run the focused scan. Expected output: 0 violations for object-alt.
5. Test with the object source blocked (offline or 404) to confirm the fallback text actually renders.
6. Evaluate replacements before adding fallback text. For SVG: inline the [svg] with a [title] child. For images: use [img alt]. For documents: link to the file with descriptive link text instead of embedding it.
7. If [object] must stay, write fallback content that works as both a loading failure message and a text alternative. Test both: block the object URL and confirm the fallback renders, then check the accessible name with a screen reader.

When to use

• Axe flags object-alt on embedded objects.
• A page embeds SVG, PDF, or media via [object] with no fallback.
• Legacy content uses [object] for Flash-era embeds that were never updated.

When not to use

• The content is a static image (use [img] with alt instead).
• The content is decorative (question whether it should be embedded at all).
• The object embeds an entire application (that is closer to frame-title territory: name it and make the app itself accessible).

Why it happens

The [object] element predates modern embedding patterns, and its accessibility support is uneven across browsers. Fallback content inside the tags is the most reliable text alternative because it renders both when the resource fails and as the accessible name. Without it, assistive tech announces an empty embedded object.

[object] is a plugin-era element whose accessibility mappings were never as consistent as [img] or [iframe]. Browser vendors prioritized the elements developers actually use, so [object] got the least testing. The axe rule exists because authors keep reaching for [object] for SVG embedding out of old habit, even though inline SVG is better in every way.

Edge cases

• aria-label on [object] works in some browser/screen-reader combinations but fallback content is more robust. Use both if you must keep [object].
• An [object] with no data attribute and no content is dead markup. Remove it.
• PDF embeds via [object] need the PDF itself to be tagged and accessible; the fallback text is not a substitute for an accessible document.
• Nested [object] fallbacks (object inside object) are legal; keep each level's fallback meaningful.
• An [object] used for HTML embedding is essentially a worse [iframe]. Prefer [iframe] with a title.
• Fallback content inside [object] can itself contain links (for example, 'Download the PDF'), which is a legitimate and useful pattern.
• Empty [object] elements with no data attribute are dead code. Remove them; do not write fallback text for nothing.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YKbhXRI2EuoloPUoLqg8Og

Resolved from the public thread: https://vectle.com/posts/pst_YKbhXRI2EuoloPUoLqg8Og

Thread query: axe-core object-alt error object element missing alt text

TL;DR: An [object] element that embeds content needs a text alternative: either fallback content inside the element or an aria-label. Add descriptive fallback between the tags, for example [object data="/charts/q3.svg"]Q3 revenue chart: revenue grew 12%.[/object]. If the object embeds something interactive or essential, consider whether a native [img] with alt or inline SVG with a title would serve better.