# 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

```text
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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