# axe-core aria-allowed-role error fallback role not supported - how to fix it

## TL;DR

Space-separated fallback roles are only allowed when the first role is unsupported; axe flags the pattern when the fallback itself is not a valid role for the element. Remove the fallback and use one correct role. One line of why: browsers use the first recognized role and ignore the rest, so a bad fallback list usually means the author was guessing.

## The error, verbatim

```text
{
  "id": "aria-allowed-role",
  "impact": "minor",
  "help": "ARIA roles must be appropriate for the element",
  "nodes": [
    { "target": [".card-link"], "failureSummary": "Fix any of the following: ARIA role button is not allowed for the given element" }
  ]
}
```

## Fix it step by step

### Step 1: Reproduce on one page

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

Expected: Violations array contains aria-allowed-role with the disallowed role named per node.

### Step 2: Check which elements carry bad roles

```bash
node -e "const r=require('./axe-allowrole.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '))})"
```

Expected: Selectors for elements whose role does not fit.

### Step 3: Find them in source

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

Expected: Shows the role assignments to correct.

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

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

Expected: Exit code 0, 0 violations. Each element now exposes a role appropriate to its element type.

### 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-role, 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 not allowed for given element

The failureSummary wording, same fix.

### axe role button not allowed on element

Common instance: role button on an anchor that should just be a button element.

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

HTML elements have implicit ARIA semantics, and not every role can override every element: a link cannot take role button in the allowed-role mapping axe enforces, and li elements only accept a short list. Authors add roles to fight the browser instead of using the right element. The fallback-role syntax (role="button link") is meant for forward compatibility, but axe flags it when the fallback role is itself inappropriate, which is the usual case. 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

- An anchor with an href is a link, if it acts like a button, change the element to button, not the role.
- li elements allow menuitem, option, radio, separator, tab, and treeitem among others, anything else fails.
- When the role is right but the element is wrong, fix the element, roles are a last resort, not a styling tool.
- 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_TxF6Y3YVAYoTIXJtMuMk6g