axe-core "aria-valid-attr-value" invalid ARIA value in CI

By Kaveh Alemi·Latchkey

axe-core rule aria-valid-attr-value found an ARIA attribute whose value is not valid. A common case is aria-labelledby or aria-describedby pointing at an id that is not present in the DOM.

What this error means

axe reports "aria-valid-attr-value: ARIA attributes must conform to valid values" and names the attribute and the value, for example "aria-labelledby=email-lbl (id does not exist)".

aria-valid-attr-value: ARIA attributes must conform to valid values (critical)
  Fix any of the following:
    ARIA attribute element ID does not exist on the page: aria-labelledby="email-lbl"
  <input type="text" aria-labelledby="email-lbl">

Common causes

An aria-labelledby or aria-describedby id is wrong

The referenced id was renamed, removed, or never rendered, so the association resolves to nothing.

An ARIA attribute holds an out-of-range value

A token like aria-checked="yes" or an aria-* set to an invalid value fails the rule because it is not one of the allowed values.

How to fix it

Point the reference at a real element id

1. Confirm the id named in the attribute is actually rendered.
2. Fix the id reference or add the missing labelling element.
3. Re-run axe to confirm the value now resolves.

<span id="email-lbl">Email</span>
<input type="text" aria-labelledby="email-lbl" />

Use only allowed token values

For state attributes use the valid tokens (aria-checked accepts true, false, mixed), not free text.

<div role="checkbox" aria-checked="true">...</div>

How to prevent it

• Keep id references in sync when elements are renamed.
• Use valid token values for ARIA state attributes.
• Run axe so broken ARIA references fail before merge.

Frequently asked questions

Related guides

References

• GitHub Actions documentation