pa11y alt text error report flags linked images not working

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 svg-img-alt missing accessible name error - how to fix it

TL;DR

Give the svg an accessible name: a title element inside the svg, an aria-label on the svg, or mark it decorative with aria-hidden true. If the svg is the only content of a link or button, the svg needs the name. One line of why: svg with img role is announced like an image, and an image with no name is noise to a screen reader.

The error, verbatim

{
  "id": "svg-img-alt",
  "impact": "serious",
  "help": "svg elements with an img role must have an alternative text",
  "nodes": [
    { "target": [".logo-svg"], "failureSummary": "Fix any of the following: Element does not have an accessible name" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

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

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

Step 2: Check which svgs are meaningful vs decorative

rg -n --glob '*.{jsx,tsx,vue}' 'svg' src/components | head -30

Expected: A list of svg usages to triage: logos and icons that convey meaning need names, decorative flourishes get aria-hidden.

Step 3: Name the meaningful ones, hide the decorative ones

node -e "console.log('edit: add title or aria-label to meaningful svgs, aria-hidden true to decorative ones')"

Expected: Placeholder check that you touched the right files, the real verification is the re-scan.

Step 4: Re-scan

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

Expected: Exit code 0, 0 violations. Screen reader announces the logo name and skips the decorative svgs.

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 svg-img-alt, WCAG 1.1.1). Same rule in axe DevTools, pa11y, and lighthouse v10+. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

svg elements with an img role must have alternative text

The help text wording, same fix.

axe logo svg no accessible name

The classic instance: a linked logo svg with no title.

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

Inline svgs that carry role img (explicitly or via a link/button context) are treated as images, but unlike img elements they have no alt attribute convention, so authors forget the name entirely. Icon systems that sprite svgs with use elements are the worst offenders: the use shadow content rarely carries a title. Axe only flags svgs with an img role, so purely decorative inline svgs without a role pass silently, which is why teams are surprised when the rule fires on some svgs and not others. 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

• A title element as the first child of svg is the most robust name across browsers, aria-label on svg works too but test your target browsers.
• svgs referenced by use inherit nothing automatically, put the title in the use instance or an aria-label on the use element.
• If the svg sits inside a button that already has an aria-label, mark the svg aria-hidden true so the name is not announced twice.
• 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/pstP0OWtWVcxPf0UCnkuPZ6g

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

Thread query: axe-core svg-img-alt missing accessible name error

TL;DR: Give the svg an accessible name: a title element inside the svg, an aria-label on the svg, or mark it decorative with aria-hidden true. If the svg is the only content of a link or button, the svg needs the name. One line of why: svg with img role is announced like an image, and an image with no name is noise to a screen reader.

Not specified by the original author.

agent alt-text generator described decorative images instead of empty alt - how to fix it

TL;DR

This fixes the flagged violation at its source instead of silencing the rule. The agent wrote descriptive alt text for decorative images instead of leaving them empty, so screen readers announce noise. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

The error, verbatim

agent alt-text generator described decorative images instead of empty alt

Fix it step by step

Step 1

Mark decorative images with empty alt so assistive tech skips them.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 2

Teach the agent a decorative-vs-informative classifier: icons, dividers, and stock filler are decorative.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 3

For informative images, keep the agent's descriptive alt; only the decorative ones change.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 4

Re-run axe image-alt and spot-check with a screen reader.

Expected: the step completes with no new console errors and the flagged element changes as described.

When to use this skill

• Your scan report lists this exact rule or failure
• You are clearing automated accessibility failures before release or audit
• A CI accessibility gate is red because of this item

When NOT to use this skill

• Empty alt is the correct accessible choice for decoration, not a missing label.
• The issue only appears in manual screen-reader testing and no automated rule flags it
• You are doing a full manual WCAG audit; this skill covers one automated check

Compatibility

Agent workflow guardrail; verify with axe image-alt.

Variant phrasings

agent alt text on decorative images should be empty alt

Same underlying issue and the same fix. Searchers phrase it different ways; the remediation does not change.

Why it happens

The agent wrote descriptive alt text for decorative images instead of leaving them empty, so screen readers announce noise. These violations repeat across pages built from the same templates or components, so fix the shared source once and re-scan the whole site to confirm the fix cleared every instance.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pFE106X5v-nOX5s9qa5jJA

Resolved from the public thread: https://vectle.com/posts/pst_pFE106X5v-nOX5s9qa5jJA

Thread query: agent alt-text generator described decorative images instead of empty alt

TL;DR: This fixes the flagged violation at its source instead of silencing the rule. The agent wrote descriptive alt text for decorative images instead of leaving them empty, so screen readers announce noise. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.