ARIA Roles Must Conform to Valid Values: How to Fix It

What this means

ARIA (Accessible Rich Internet Applications) lets you attach a role to an element so screen readers and other assistive technology understand what it is, for example a button, a navigation region, or a dialog. The catch is that the role value must come from a fixed list defined in the WAI-ARIA specification. This audit issue fires when an element carries a role whose value is not on that list.

A role becomes invalid in three common ways: a misspelling such as role="navigaton"; a made-up value that sounds plausible but does not exist, such as role="dropdown"; or an abstract role that the spec reserves for its own taxonomy and forbids in content, such as role="widget" or role="input".

Why it matters

When a role value is not recognized, the browser and assistive technology do not silently guess what you meant. They ignore the invalid role and fall back to the element's native semantics, or expose nothing useful at all. A screen reader user then hears a generic, unlabeled element instead of the button, tab, or dialog you built, so the control becomes confusing or unusable. Abstract roles are worse than ignored: user agents are required by spec not to map them to the accessibility API, so they never reach the user.

This maps to WCAG 2.1 Success Criterion 4.1.2 Name, Role, Value, which requires that the role of every user-interface component be programmatically determinable. Deque rates the underlying axe rule as a Critical impact issue because a broken role can hide an interactive component from everyone who relies on assistive technology. There is a growing second reason to care: the same machine-readable semantics that help screen readers also help AI crawlers and answer engines parse your page structure, which is why clean, valid markup is part of building a machine-readable web.

The invalid roles you will actually see

Almost every real-world failure is one of a handful of patterns. Find the row that matches your flagged value, and the fix column tells you where to go.

How to detect it

Because a role is either in the spec or it is not, automated tools catch this with near-perfect accuracy. Any of these three will name the bad value.

1. axe DevTools (browser extension). Run a scan; the rule is aria-roles, "ARIA roles used must conform to valid values." It reports the element and the exact unrecognized token so you can correct it in place.
2. Google Lighthouse. In the Chrome Lighthouse Accessibility report the same check appears as "[role] values are not valid," listing every failing node on the page at once.
3. ARIA DevTools (browser extension). It renders the accessibility tree; an element you expected to appear as a dialog or tab that instead shows up as a plain generic node is your invalid role, caught by what the value did (nothing) rather than how it was spelled.

How to fix it

Look at the flagged value and decide which of three fixes applies. First, if it is a typo, correct the spelling. Second, if the concept exists in ARIA under a different name, swap in the real role. Third, and best, if a native HTML element already carries that meaning, drop the role and use the element instead, because native semantics are more reliable than ARIA.

<!-- Invalid: typo, made-up value, and abstract role -->
<div role="naviagtion">...</div>
<div role="dropdown">...</div>
<span role="widget">...</span>

<!-- Fixed: corrected spelling -->
<div role="navigation">...</div>

<!-- Fixed: real ARIA role for the concept -->
<ul role="menu">...</ul>

<!-- Best: use native HTML, no role needed -->
<nav>...</nav>
<button type="button">Open menu</button>

After you assign a valid role, confirm the role still fits the element and that you have supplied any states or properties that role requires. A correct role with missing support can trigger sibling issues such as required ARIA attributes must be provided and elements must only use allowed ARIA attributes. Re-run the scan to confirm the element clears.

False positives

This rule has very few false positives, because a role is either in the spec or it is not. Two situations look like errors but are valid. A role attribute can hold a space-separated fallback list, such as role="doc-chapter region", where the browser uses the first valid token; axe accepts this. Newer roles, including the DPUB-ARIA and Graphics ARIA extensions, are valid even though they may look unfamiliar. If you believe a flag is wrong, verify the exact value against the spec rather than assuming the scanner is mistaken, since the most common "false positive" turns out to be a real typo.

FAQ

Related checks

• Elements must only use allowed ARIA attributes
• Required ARIA attributes must be provided
• aria-hidden must not contain focusable elements