# a11y scan agent failed to inject axe into shadow root - how to fix it

## TL;DR

Inject at the document level and let axe's flattened tree handle shadow DOM: axe-core 4.3+ analyzes open shadow roots automatically, so the agent does not need per-shadow-root injection. The failure usually means an old axe-core or a closed shadow root. One line of why: axe composes the flattened tree itself, per-root injection fights the tool's own design.

## The error, verbatim

```text
ScanAgentError: failed to inject axe into shadow root
    host: my-datepicker (open shadow root)
    axe-core: 4.1.0 (bundled with agent)

```

## Fix it step by step

### Step 1: Reproduce the injection failure

```bash
node agent/run-audit.js --route /booking | rg -i 'shadow|inject' | head -5
```

Expected: The shadow-root injection error repeats.

### Step 2: Check the bundled axe version

```bash
node -e "console.log(require('axe-core/package.json').version)"
```

Expected: An old bundled axe-core explains the failure; upgrade the agent's dependency.

### Step 3: Upgrade and simplify

```bash
npm install axe-core@^4.8 --save | tail -2
```

Expected: Modern axe-core handles open shadow roots via the flattened tree with document-level injection.

### Step 4: Re-run the audit

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

Expected: Shadow DOM content is analyzed with no per-root injection.

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

Scan agent with axe-core 4.8+. Closed shadow roots remain unauditable by design. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent axe shadow dom injection failed

Same failure, same upgrade.

### axe cannot see web component content

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

Older agent harnesses tried to inject axe into each shadow root individually because early axe-core had weak shadow support. Modern axe-core builds the flattened tree from a document-level injection and analyzes open shadow roots automatically. Agents carrying old axe-core bundles hit injection failures on web-component-heavy pages. Closed shadow roots are intentionally opaque to all scripts including axe, so components using them need vendor cooperation or replacement. 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

- Closed shadow roots cannot be audited by any agent-side technique, flag the component to the vendor.
- After upgrading, delete the per-root injection code, it now fights the flattened-tree analysis.
- Slotted content is analyzed at its composed position, which is correct but can surprise node targeting.
- 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_2W4nBiJ_ESuB6mtRj5qBiQ