pa11y-ci "failed with N errors" threshold exceeded in CI

pa11y-ci ran HTML CodeSniffer against each URL and one or more pages returned more errors than the threshold you set (default 0). It prints per-URL error counts and exits non-zero, failing the job.

What this error means

pa11y-ci output shows "x https://... - N errors" and a final summary with a failing URL count, then the process exits 2. The run stops the pipeline once any page exceeds threshold.

pa11y-ci

Running Pa11y on 3 URLs:
 x http://localhost:3000/ - 4 errors
 > http://localhost:3000/about - 0 errors

Errors in http://localhost:3000/:
 - Anchor element found with a valid href attribute, but no link content...

Failed to run because of errors. 4 total errors across 1 URL.

Common causes

New accessibility errors were introduced

A page now emits more errors than the threshold allows, usually from markup added since the last passing run.

The threshold is set to zero

With threshold: 0, any single error fails the build. Pre-existing issues on a newly crawled URL will trip it immediately.

How to fix it

Fix the reported errors

Read the "Errors in <url>" section for each rule and selector.
Apply the WCAG fix (add link text, alt, label) for each.
Re-run pa11y-ci to confirm the URL is back under threshold.

Terminal

pa11y-ci --config .pa11yci.json

Set thresholds deliberately in config

If you are burning down a backlog, set a per-run threshold and lower it over time, rather than leaving errors unbounded.

.pa11yci.json

{
  "defaults": { "threshold": 0, "timeout": 30000 },
  "urls": ["http://localhost:3000/", "http://localhost:3000/about"]
}

How to prevent it

Run pa11y-ci on every PR so new errors are caught early.
Keep the threshold at 0 once a page is clean to prevent regressions.
Track and burn down errors on legacy pages with explicit thresholds.