# cypress-axe failed cannot read properties of undefined - how to fix it

## TL;DR

Find which object is undefined: it is usually cy.get yielding nothing, axe not injected before checkA11y, or a custom command mis-wired. Run the spec headed and read the stack frame. One line of why: cypress-axe is a thin wrapper, and cannot read properties of undefined almost always comes from the test code around it, not from axe itself.

## The error, verbatim

```text
TypeError: Cannot read properties of undefined (reading 'run')
    at checkA11y (node_modules/cypress-axe/dist/index.js)
    at Context.eval (cypress/e2e/a11y.cy.js:18:5)

```

## Fix it step by step

### Step 1: Reproduce headed to see the stack

```bash
npx cypress run --spec cypress/e2e/a11y.cy.js | rg -B2 -A8 'TypeError' | head -30
```

Expected: The stack shows whether the undefined is the axe object, the subject, or a config.

### Step 2: Verify injectAxe ran first

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

Expected: Confirms injectAxe is called before checkA11y in the same test, the classic ordering bug.

### Step 3: Check the custom command wiring

```bash
rg -n 'checkA11y|injectAxe' cypress/support/commands.js | head -10
```

Expected: Shows how the commands are registered; a typo here produces the undefined.

### Step 4: Fix the ordering and re-run

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

Expected: Spec passes with real violation output or a clean run, no TypeError.

### 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 and axe-core 4.x. The injectAxe/checkA11y pairing is the API contract. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### cypress-axe cannot read properties undefined reading run

The full error, an ordering or wiring bug in the spec.

### checkA11y undefined error

Practitioner phrasing, same triage.

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

Cypress-axe exposes injectAxe (loads axe into the app iframe) and checkA11y (runs it). Calling checkA11y without injectAxe, or in a before hook that runs before cy.visit, leaves the axe handle undefined and produces this TypeError. The other common shape is a custom Cypress command that shadows or mis-registers checkA11y. Axe itself is innocent in nearly every instance of this error. 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

- injectAxe must run after cy.visit in the same test, not in a before hook for a different spec.
- If you use cypress-axe with component testing, the injection target differs, check the docs for the CT pattern.
- Do not catch and swallow this TypeError, it masks a broken harness, not a passing audit.
- 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_tNpJT-02JXPzPcI2SzVqpg