# axe-core aria-allowed-attr error unsupported aria attribute - how to fix it

## TL;DR

Remove or replace the aria attribute the element's role does not support: check the ARIA spec for which attributes each role allows, then delete the offender or move it to an element whose role allows it. One line of why: unsupported aria attributes are ignored by assistive tech, so the information you thought you conveyed never arrives.

## The error, verbatim

```text
{
  "id": "aria-allowed-attr",
  "impact": "critical",
  "help": "ARIA attributes must be valid for the element role",
  "nodes": [
    { "target": ["[aria-checked].toggle"], "failureSummary": "Fix any of the following: ARIA attribute is not allowed: aria-checked" }
  ]
}
```

## Fix it step by step

### Step 1: Reproduce on one page

```bash
npx @axe-core/cli https://example.com --rules aria-allowed-attr --save axe-attr.json
```

Expected: Violations array contains aria-allowed-attr with the attribute name in each failure summary.

### Step 2: Extract the offending attribute names

```bash
node -e "const r=require('./axe-attr.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '), '-', n.failureSummary.match(/not allowed: ([\w-]+)/)[1])})"
```

Expected: Pairs each selector with its disallowed attribute.

### Step 3: Find them in source

```bash
rg -n 'aria-checked' src --glob '*.{jsx,tsx,vue}' | head -20
```

Expected: Shows where the bad attribute is set, substitute your attribute name.

### Step 4: Fix the attributes and re-scan

```bash
npx @axe-core/cli https://example.com --rules aria-allowed-attr
```

Expected: Exit code 0, 0 violations. The widget still announces its state because the attribute now lives on a role that supports it.

### Step 5: Gate the rule in CI

```bash
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-allowed-attr, WCAG 4.1.2). Catches typos like aria-labeledby too, which is really the aria-valid-attr sibling rule. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### aria attribute is not allowed aria-checked

The failureSummary wording, same fix.

### axe unsupported aria attribute on role

General phrasing, fix is always remove, replace, or move the attribute.

### 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

Every ARIA role supports a defined set of states and properties, and authors routinely copy aria attributes between widgets (aria-checked from a checkbox onto a toggle button with role switch is fine, onto a plain button is not). Axe validates each attribute against the element's computed role. Custom elements and web components are frequent offenders because the role is set in shadow DOM while the attributes sit on the host. 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

- aria-checked is allowed on checkbox, radio, menuitemcheckbox, menuitemradio, and switch, not on button, move it or change the role.
- Global aria attributes (aria-label, aria-hidden, aria-describedby and friends) are allowed on every role, the rule knows the global list.
- Misspelled attributes like aria-labeledby fail the sibling rule aria-valid-attr instead, check both rules when cleaning up.
- 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_8AMQnMHsFBaF9lO28WxMTg