pa11y "WCAG2AA.Principle1..." error code in CI

pa11y reports each issue with an HTML CodeSniffer code such as WCAG2AA.Principle1.Guideline1_1.1_1_1.H37. The code encodes the WCAG principle, guideline, success criterion, and the specific technique that failed.

What this error means

pa11y output lists an error with a WCAG2AA.Principle... code, a type of "error", and the selector, for example an image missing alt (H37) or a form control missing a label (H44).

Errors in http://localhost:3000/:

 - WCAG2AA.Principle1.Guideline1_1.1_1_1.H37
   Img element missing an alt attribute. Use the alt attribute to specify a short
   text alternative.
   (#main > img)

Common causes

A specific WCAG success criterion is not met

The code maps to a real criterion: 1_1_1 is non-text content (alt text), 1_4_3 is contrast, 4_1_2 is name/role/value. The technique suffix (H37, H44) names the fix.

Markup changed and now trips a technique check

HTML CodeSniffer statically inspects the DOM; new or edited markup can newly match a failing technique.

How to fix it

Map the code to its fix and apply it

1. Decode the code: the last segment (H37, H44, G18) is the technique.
2. Apply that technique (H37 = add alt, H44 = associate a label, G18 = meet contrast).
3. Re-run pa11y to confirm the code no longer appears.

<!-- H37: add alt text -->
<img src="/logo.png" alt="Company logo" />

Ignore a confirmed false positive by code

If a specific code is a verified false positive, add it to the ignore list with a note, rather than silencing pa11y entirely.

{ "defaults": { "ignore": ["WCAG2AA.Principle1.Guideline1_4.1_4_3.G18"] } }

How to prevent it

• Learn the common codes so failures are quick to triage.
• Fix the underlying criterion instead of ignoring codes broadly.
• Keep the ignore list documented with a justification per code.

Related guides