# 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

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

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

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

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

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

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

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/pst_UUue09eFwLUv462_zNMS7A