axe-core error flattened tree on shadow dom bug

axe-core error flattened tree on shadow dom bug - how to fix it

TL;DR

Let axe see the shadow DOM: upgrade axe-core past 4.3 where flattened-tree shadow support landed, and make sure your test setup does not serialize the page to outerHTML (which drops shadow roots). If the flattened tree still confuses the scan, audit the shadow host's inner content directly. One line of why: axe analyzes the flattened accessibility tree, and older versions or HTML-serialization harnesses lose the shadow content entirely.

The error, verbatim

Error: axe-core could not build flattened tree for shadow host
    selector: my-datepicker (shadow root attached)
    axe-core 4.2.0

Fix it step by step

Step 1: Check the axe-core version

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

Expected: Shows the installed version; below 4.3 explains the flattened-tree failure.

Step 2: Upgrade axe-core

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

Expected: Installs a version with full shadow DOM flattened-tree support.

Step 3: Verify shadow content is reachable

node -e "console.log('re-run the scan and check the shadow host nodes appear in results')"

Expected: Re-scan shows the shadow DOM nodes analyzed instead of erroring.

Step 4: Re-run the audit

npx @axe-core/cli https://example.com/ --save axe-shadow.json | tail -3

Expected: Scan completes with shadow DOM content included in results.

Step 5: Re-run twice to rule out flakes

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

axe-core 4.3+ for flattened-tree shadow DOM support; 4.8+ recommended. Web component heavy apps need this. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

axe flattened tree shadow dom

Same error, same upgrade fix.

axe shadow root not analyzed

Practitioner phrasing, also caused by HTML-serializing harnesses.

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 builds a flattened tree (light DOM plus shadow DOM composed together) to analyze web components. Axe-core before 4.3 had incomplete shadow support and errored on complex shadow trees. Separately, harnesses that serialize the page to an HTML string and re-parse it silently drop shadow roots, since shadow DOM is not in outerHTML. The fix is version plus harness: modern axe-core and a harness that passes the live DOM. 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

• Closed shadow roots are invisible to axe by design, use open shadow roots for testable components.
• Slotted content is analyzed at its flattened position, which can surprise selectors, check the composed tree.
• If a third-party component uses closed shadow DOM, you cannot audit inside it, ask the vendor.
• 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_pZH-k-OAQshpKqp39WGstQ