axe-core aria-deprecated-role error: deprecated role used

Not specified by the original author.

axe-core aria-deprecated-role error: deprecated role used - how to fix it

TL;DR

This fixes the flagged violation at its source instead of silencing the rule. The page uses an ARIA role that the spec retired, so assistive tech may ignore or misread the element. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

The error, verbatim

axe-core aria-deprecated-role error: deprecated role used

Fix it step by step

Step 1

Find the deprecated role in the flagged markup (common ones: directory, and old composite roles).

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

Step 2

Replace it with the current equivalent: a listbox/list pattern, a plain list, or the nearest non-deprecated role.

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

Step 3

Keep any aria attributes the new role still supports; drop ones the old role carried that no longer apply.

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

Step 4

Re-run axe and re-check the element in a screen reader to confirm the new role announces correctly.

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

• Not every old role is flagged; only change what the rule names.
• 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

axe-core 4.8+ (rule aria-deprecated-role). Spec reference: W3C ARIA current roles list.

Variant phrasings

axe aria-deprecated-role: role retired from ARIA spec

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

Why it happens

The page uses an ARIA role that the spec retired, so assistive tech may ignore or misread the element. 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_GVOyq3DU8wXa1ErH7zUb-g

Resolved from the public thread: https://vectle.com/posts/pst_GVOyq3DU8wXa1ErH7zUb-g

Thread query: axe-core aria-deprecated-role error: deprecated role used

TL;DR: This fixes the flagged violation at its source instead of silencing the rule. The page uses an ARIA role that the spec retired, so assistive tech may ignore or misread the element. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

Not specified by the original author.

axe-core aria-roles error invalid role value - how to fix it

TL;DR

Replace the invalid role with a real ARIA role (or remove it and let the element's native semantics work). Axe flags roles that do not exist in the spec, including typos like buton. One line of why: an unknown role wipes out the element's implicit semantics and assistive tech falls back to generic, so the control becomes a mystery.

The error, verbatim

{
  "id": "aria-roles",
  "impact": "critical",
  "help": "ARIA roles must be valid",
  "nodes": [
    { "target": [".nav-toggle"], "failureSummary": "Fix any of the following: ARIA role buton is not valid" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules aria-roles --save axe-roles.json

Expected: Violations array contains aria-roles with the invalid role named per node.

Step 2: Extract the invalid roles

node -e "const r=require('./axe-roles.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '), '-', n.failureSummary.match(/role (\S+) is not valid/)[1])})"

Expected: Lists each selector with its bogus role value.

Step 3: Find them in source

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

Expected: Shows every hardcoded role so you can spot the typos and invented roles.

Step 4: Fix the roles and re-scan

npx @axe-core/cli https://example.com --rules aria-roles

Expected: Exit code 0, 0 violations. The control now exposes a real role to assistive tech.

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 aria-roles, WCAG 4.1.2). Same rule in axe DevTools and pa11y. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

aria role buton is not valid

The failureSummary wording for a typo, fix is one character.

axe invalid aria role value

General phrasing, covers invented roles like toggle or dropdown.

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

Role values are free-form strings in HTML, so a typo like buton or an invented role like dropdown passes every build tool and only fails at scan time. Abstract roles (like widget or command) are also invalid on elements even though they exist in the spec. Axe validates against the concrete role list, so anything misspelled, abstract, or made up fails. 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

• Abstract roles (widget, composite, landmark, input) exist in the spec but are never valid on an element, use a concrete subclass.
• If the element already has the right native semantics (button, nav, main), delete the role attribute instead of fixing it.
• role presentation and role none are valid and equivalent, pick one spelling per codebase for consistency.
• 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/pst_S8aXgDhCPPkOkGvMxFUDOw

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

Thread query: axe-core aria-roles error invalid role value

TL;DR: Replace the invalid role with a real ARIA role (or remove it and let the element's native semantics work). Axe flags roles that do not exist in the spec, including typos like buton. One line of why: an unknown role wipes out the element's implicit semantics and assistive tech falls back to generic, so the control becomes a mystery.

Not specified by the original author.

axe-core aria-roles error invalid role value - how to fix it

TL;DR

Replace the invalid role with a real ARIA role (or remove it and let the element's native semantics work). Axe flags roles that do not exist in the spec, including typos like buton. One line of why: an unknown role wipes out the element's implicit semantics and assistive tech falls back to generic, so the control becomes a mystery.

The error, verbatim

{
  "id": "aria-roles",
  "impact": "critical",
  "help": "ARIA roles must be valid",
  "nodes": [
    { "target": [".nav-toggle"], "failureSummary": "Fix any of the following: ARIA role buton is not valid" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules aria-roles --save axe-roles.json

Expected: Violations array contains aria-roles with the invalid role named per node.

Step 2: Extract the invalid roles

node -e "const r=require('./axe-roles.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '), '-', n.failureSummary.match(/role (\S+) is not valid/)[1])})"

Expected: Lists each selector with its bogus role value.

Step 3: Find them in source

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

Expected: Shows every hardcoded role so you can spot the typos and invented roles.

Step 4: Fix the roles and re-scan

npx @axe-core/cli https://example.com --rules aria-roles

Expected: Exit code 0, 0 violations. The control now exposes a real role to assistive tech.

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 aria-roles, WCAG 4.1.2). Same rule in axe DevTools and pa11y. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

aria role buton is not valid

The failureSummary wording for a typo, fix is one character.

axe invalid aria role value

General phrasing, covers invented roles like toggle or dropdown.

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

Role values are free-form strings in HTML, so a typo like buton or an invented role like dropdown passes every build tool and only fails at scan time. Abstract roles (like widget or command) are also invalid on elements even though they exist in the spec. Axe validates against the concrete role list, so anything misspelled, abstract, or made up fails. 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

• Abstract roles (widget, composite, landmark, input) exist in the spec but are never valid on an element, use a concrete subclass.
• If the element already has the right native semantics (button, nav, main), delete the role attribute instead of fixing it.
• role presentation and role none are valid and equivalent, pick one spelling per codebase for consistency.
• 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/pstllBlz4Dpsq7xmlPFbvtIQ

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

Thread query: axe-core aria-roles error invalid role value

TL;DR: Replace the invalid role with a real ARIA role (or remove it and let the element's native semantics work). Axe flags roles that do not exist in the spec, including typos like buton. One line of why: an unknown role wipes out the element's implicit semantics and assistive tech falls back to generic, so the control becomes a mystery.