# scan agent crashed running axe-core on huge dom - how to fix it

## TL;DR

Scope the agent's axe runs to regions instead of the whole document, and cap DOM size before scanning: if the node count is over the agent's budget, split by landmark or route. Axe in a constrained agent browser tab dies the same way pa11y tabs do. One line of why: analysis cost scales with DOM size, and an agent that always scans document-wide will always crash on the biggest pages.

## The error, verbatim

```text
ScanAgentError: tab crashed during axe-core analysis
    dom_nodes: 48000
    url: https://example.com/reports/all

```

## Fix it step by step

### Step 1: Reproduce the crash

```bash
node agent/run-audit.js --route /reports/all | rg -i 'crash' | head -3
```

Expected: The tab crash repeats on the huge-DOM route.

### Step 2: Measure the DOM

```bash
node agent/measure.js --route /reports/all | rg -i 'nodes' | head -3
```

Expected: Confirms tens of thousands of nodes, over the agent's safe budget.

### Step 3: Add region-scoped scanning

```bash
rg -n 'axe.run|context' agent/scanner.js | head -10
```

Expected: Find the axe invocation to scope context per landmark region.

### Step 4: Re-run with scoping

```bash
node agent/run-audit.js --route /reports/all | tail -4
```

Expected: Agent scans region by region and completes without crashing.

### Step 5: Add a regression probe

```bash
node agent/run-audit.js --smoke | tail -3
```

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

## When to use this skill

- You run an agent that scans UIs for accessibility and it hits this breakdown
- The agent's scan loop stalls, crashes, or loops on this exact failure
- You are hardening an audit agent's error handling for production scans

## When NOT to use this skill

- A human runs the scan manually and it works, this is agent-harness failure handling
- The scan completes and only reports violations, use the rule-specific skills

## Compatibility

Audit agent harness running axe-core 4.8+ in Playwright/Puppeteer. Region scoping uses axe context selectors. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent axe crash large dom

Same crash, same scoping fix.

### scan agent tab died huge page

Practitioner phrasing.

### the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

## Why it happens

Agents default to axe.run on the whole document because it is the simplest call, and on pages with tens of thousands of nodes the analysis exhausts the tab's memory. The agent then reports a crash instead of violations, and naive retries crash again. Region-scoped audits (one axe run per landmark) keep each analysis small, and the union of region results covers the page. As a bonus, region scoping maps violations to page areas, which makes remediation tickets better. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

## Edge cases

- Set a DOM node budget (e.g. 15k) above which the agent auto-switches to region scoping.
- Virtualized lists still crash naive scans if the agent scrolls everything into existence first, scope before expanding.
- Report the crash distinctly from violations so dashboards do not show a crashed page as clean.
- Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_HxRSBszDTxmWnMV6jfKYlw