pa11y-ci failed threshold exceeded blocking deploy

pa11y-ci failed threshold exceeded blocking deploy - how to fix it

TL;DR

Triage the threshold breach instead of just raising the number: run pa11y-ci locally to see which pages and rules breached, fix the real violations, and only then adjust the threshold to a defensible value. The gate is doing its job. One line of why: thresholds count violations, so a breach means the site got worse, and silencing the gate hides the regression.

The error, verbatim

Error: pa11y-ci threshold exceeded: 14 errors (threshold: 5)
    failing pages: /pricing, /checkout
    blocking deploy

Fix it step by step

Step 1: Reproduce the breach locally

npx pa11y-ci --config .pa11yci.json | rg -i 'threshold|error' | head -10

Expected: The threshold breach reproduces with the same counts.

Step 2: See which rules breached

npx pa11y-ci --config .pa11yci.json | rg -i 'error|warning' | head -20

Expected: Lists the failing pages and rules behind the count.

Step 3: Fix the real violations

npx pa11y https://example.com/pricing --reporter cli | head -20

Expected: Rule-specific failures on the breaching pages to fix one by one.

Step 4: Re-run the gate

npx pa11y-ci --config .pa11yci.json | tail -4

Expected: Counts drop under threshold and the deploy unblocks.

Step 5: Re-run twice to rule out flakes

npx pa11y https://example.com/ | tail -2

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

When to use this skill

• The scan tool itself fails or crashes instead of reporting violations
• Your a11y CI step errors out before any rule results appear
• You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

When NOT to use this skill

• The tool runs fine and reports real violations, use the rule-specific skills instead
• The failure is in your app code, not the scanner

Compatibility

pa11y-ci 3.x with a .pa11yci.json config. Thresholds count errors, warnings, and notices separately. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

pa11y-ci threshold exceeded

Same gate failure, same triage.

pa11y blocking deploy

Practitioner phrasing, the gate is red and deploys are stuck.

same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

Why it happens

Pa11y-ci counts issues by type against per-type thresholds, and deploys block when counts exceed them. Breaches come from real regressions (a new component ships violations), threshold misconfiguration (threshold 0 on a legacy site), or scan instability (flaky pages inflating counts). The counts are the signal: fix the violations first, then set thresholds to the cleaned-up baseline plus a small buffer. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

Edge cases

• Set thresholds from a clean baseline run, not from guesses, and re-baseline after intentional changes.
• Separate thresholds per URL in config for pages with different risk profiles.
• Flaky counts usually mean flaky pages (timing), fix the wait conditions before blaming the threshold.
• Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstUUue09eFwLUv462zNMS7A