Elements Must Only Use Allowed ARIA Attributes: How to Fix It
- February 2, 2023
- Accessibility, ARIA
Elements Must Only Use Allowed ARIA Attributes: How to Fix It
TL;DR: This issue fires when an element carries an aria-* attribute that is not permitted for its role. The fix is to remove the attribute that does not belong, switch to a role that actually supports it, or drop the ARIA entirely and use a native HTML element that already has the right semantics. It maps to WCAG 4.1.2 Name, Role, Value.
What this means
Every ARIA role has a defined set of states and properties it is allowed to use. The WAI-ARIA specification sorts these into required attributes, supported attributes, and attributes inherited from parent roles. When you place an aria-* attribute on an element whose role does not list that attribute, the pairing is invalid. The axe rule name is aria-allowed-attr, and the plain-language version is "Elements must only use allowed ARIA attributes."
A common example: aria-checked is only valid on roles such as checkbox, radio, menuitemcheckbox, and menuitemradio. Put it on a plain link or a generic div with no matching role and it is not allowed there.
Why it matters
When assistive technology meets a role-attribute mismatch, it has no reliable way to interpret the extra attribute. It may ignore the attribute, or it may announce or behave in an unexpected way. At best the disallowed attribute does nothing; at worst it blocks access to a whole region of the interface. Screen reader users can end up with a control that is mislabeled, mis-stated, or simply unusable.
This is a Name, Role, Value problem under WCAG 2.1 Success Criterion 4.1.2 (Level A). The criterion requires that the name, role, states, and properties of every user-interface component can be programmatically determined. A disallowed ARIA attribute breaks that contract because the role and the property contradict each other. Clean ARIA also keeps your markup machine-readable for the growing set of automated and AI agents that parse the page, not just traditional screen readers.
How it gets flagged
Automated tools surface this without much effort:
- axe-core / axe DevTools report it under the rule ID
aria-allowed-attrwith the message "Elements must only use allowed ARIA attributes" (newer versions phrase it as "supported ARIA attributes"). - Google Lighthouse includes the same check in its Accessibility category as "[aria-*] attributes are not allowed for this element's role."
- Most other scanners (WAVE, Accessibility Insights, and SEO ProCheck's accessibility module) flag the same condition.
The report names the element, its role, and the offending attribute, which is enough to act on directly.
How to fix it
1. Identify the element's role
Check for an explicit role attribute. If there is none, the element uses the implicit role of its tag. For instance, <input type="checkbox"> has the implicit role checkbox, and <nav> has the role navigation.
2. Remove attributes not valid for the role
Look up the role in the WAI-ARIA specification and check its required, supported, and inherited attributes. Delete any aria-* attribute that is not on that list.
<!-- Bad: aria-checked is not allowed on a link -->
<a href="/filter" aria-checked="true">Show in stock</a>
<!-- Good: drop the disallowed attribute -->
<a href="/filter">Show in stock</a>3. Use a role that supports the attribute
If the attribute really is needed, the element is probably the wrong role. Give it a role that lists that attribute as required or supported.
<!-- Good: aria-checked is valid on role="checkbox" -->
<span role="checkbox" tabindex="0" aria-checked="true">
Show in stock
</span>4. Prefer native HTML
The first rule of ARIA is to use a native element when one provides the semantics and keyboard behavior you need. Native controls carry the correct role and state support for free, so the mismatch cannot happen.
<!-- Best: native checkbox, no ARIA needed -->
<label>
<input type="checkbox" checked> Show in stock
</label>False positives
Genuine false positives are rare, but a few cases are worth checking before you change code. Global ARIA attributes such as aria-label, aria-hidden, and aria-describedby are allowed almost everywhere; if one is flagged, the element more likely has an unusual or contradictory role that narrows what is permitted. If a framework or component library injects the attribute at runtime, confirm what is actually in the rendered DOM rather than the source template. And if an attribute is added by script only when a matching role is also present, test the live state rather than the initial markup.
Want a full sweep of your site's ARIA and accessibility issues, prioritized and explained?
FAQ
Is this the same as the "prohibited ARIA attributes" issue?
No, but they are close cousins. "Allowed" (aria-allowed-attr) checks that an attribute is valid for the element's role. "Prohibited" (aria-prohibited-attr) flags attributes such as aria-label on elements that should not be named at all. Both come down to matching attributes to the correct role.
Will an invalid attribute always break the page?
Not always, and that is the risk. Many assistive technologies simply ignore the disallowed attribute, so the page may seem fine in casual testing. But behavior is undefined, so some tools will mis-announce or mishandle the control. Fix it rather than relying on it being ignored.
How do I know which attributes a role allows?
Each role in the WAI-ARIA specification lists its required, supported, and inherited states and properties. Look up the role, compare that list to the attributes on your element, and remove anything that is not present.
Should I add a role to keep the attribute, or remove the attribute?
Ask what the element is meant to do. If it genuinely behaves like a checkbox or tab, give it the matching role (and the keyboard support that role implies). If the attribute was a leftover or copy-paste error, just remove it. When in doubt, reach for a native HTML element instead.
Related checks
Claude Vincent is a technical SEO consultant focused on crawlability, rendering, and AI-search visibility. He writes the field guides and case studies at SEO ProCheck, with a bias toward the durable, unglamorous work that decides whether search engines and AI answer engines can actually read and cite a site.
About SEO ProCheck
Technical SEO consulting and GEO strategy with 20 years of enterprise experience. Case studies, resources, and tools for search and AI visibility.
Work With Me
Technical SEO audits, GEO strategy, site migrations, and international SEO. Hourly consulting for teams who need hands-on support, not just reports.
Subscribe to our newsletter!
