lighthouse accessibility score failed ci threshold error

lighthouse accessibility score failed ci threshold error - how to fix it

TL;DR

Find which audits drag the score down, fix the highest-weight ones first, then set the threshold to a value your pipeline can hold. The score is a weighted average, so one failing heavyweight audit (like color contrast across the page) tanks it. One line of why: the CI assertion compares a weighted composite, not individual rules, so you fix the score by fixing the heaviest failing audits.

The error, verbatim

Error: Lighthouse accessibility score 82 is below threshold 90
    at assert (node_modules/@lhci/cli/src/assert.js)
    url: https://example.com/

Fix it step by step

Step 1: Reproduce the score locally

npx lighthouse https://example.com/ --only-categories=accessibility --chrome-flags='--headless' --output=json --output-path=lh.json | tail -3

Expected: Produces lh.json with the category score and per-audit results.

Step 2: List failing audits by weight

node -e "const r=require('./lh.json'); const a=r.audits; Object.entries(a).forEach(function([k,v]){if(v.score!==null&&v.score!==1)console.log(k, v.score, v.details&&v.details.items?v.details.items.length+' items':'')})"

Expected: Shows each failing audit with its score and item count, the biggest item counts are your leverage.

Step 3: Fix the top failing audits

node -e "console.log('fix color-contrast, image-alt, link-name first: they carry the most weight')"

Expected: Apply the rule-specific fixes, then move to the next failing audit.

Step 4: Re-run and tune the threshold

npx lhci assert --preset=lighthouse:recommended | tail -5

Expected: Assertion passes; set the threshold to the score you can hold, not an aspirational 100.

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

Lighthouse 10/11, LHCI (lighthouse-ci) for assertions. Thresholds live in lighthouserc assert config. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

lighthouse ci accessibility assertion failed

Same failure via LHCI assert, same fix.

lighthouse a11y score below 90

Practitioner phrasing, the fix is audit-by-audit, not threshold-lowering alone.

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

The accessibility score weights audits, and a handful of page-wide failures (contrast, missing alt, missing names) dominate it. Teams watch the score drop after a redesign ships a new component with baked-in violations. The threshold in CI is often set aspirationally (90 or 95) without a plan to fix the underlying audits, so the gate goes red and stays red. The durable fix is clearing the heavyweight audits; the pragmatic fix is a threshold the team can actually hold while fixing. 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

• Never just lower the threshold to green without a fix plan, that is how the gate rots.
• Score varies run to run on dynamic pages, set thresholds a few points below your stable average to avoid flakes.
• Manual audits (not automated) do not affect the score, the CI gate only sees what lighthouse can check.
• 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/pst_natUsdo2cPs7He4MOmAq1g