# cypress-axe error timed out waiting for a11y audit - how to fix it

## TL;DR

Give the audit time or shrink what it chews on: raise the Cypress command timeout for checkA11y, scope the audit to a smaller context, and check the page is not still loading. Axe on a huge DOM inside Cypress's constrained browser can take a minute. One line of why: Cypress default timeouts assume fast commands, and a full-page axe analysis is not a fast command.

## The error, verbatim

```text
Error: Timed out retrying after 4000ms: checkA11y did not complete
    at checkA11y (node_modules/cypress-axe/dist/index.js)
    page: /reports/all (12k DOM nodes)

```

## Fix it step by step

### Step 1: Reproduce the timeout

```bash
npx cypress run --spec cypress/e2e/a11y.cy.js | rg -i 'timed out' | head -5
```

Expected: The checkA11y timeout repeats on the heavy page.

### Step 2: Time a manual axe run

```bash
npx @axe-core/cli https://example.com/reports/all --save /dev/null | tail -2
```

Expected: If the CLI also takes very long, the DOM is the problem, not Cypress.

### Step 3: Raise the timeout and scope the audit

```bash
rg -n 'checkA11y' cypress/e2e/a11y.cy.js | head -5
```

Expected: Add a timeout option to checkA11y and scope context to the content region.

### Step 4: Re-run the spec

```bash
npx cypress run --spec cypress/e2e/a11y.cy.js | tail -4
```

Expected: Spec completes the audit within the raised timeout.

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

cypress-axe 1.x with Cypress 12/13. checkA11y accepts timeout and context options. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### checkA11y timed out

Same error, same fix.

### cypress axe audit timeout heavy page

Practitioner phrasing, the DOM is usually huge.

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

Axe analysis time scales with DOM size and rule count, and Cypress wraps checkA11y in its command timeout (default 4 seconds), which a big page blows past. CI runners with throttled CPU stretch it further. The fix has two levers: more time (timeout option) and less work (context scoping, fewer rules). Scoping to the region under test is usually the right call anyway, since the spec is testing a feature, not the whole app shell. 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

- Scope checkA11y context to the feature under test, auditing the whole app in every spec is slow and noisy.
- Run the heavy a11y specs serially, parallel Cypress runners on small CI machines starve the browser.
- If the CLI scan is fast but Cypress times out, the Cypress browser constraints (memory, CPU) are the bottleneck.
- 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_567ll019kzgdwn2hUkD4Zw