axe-core table-headers error missing th scope failed

axe-core table-headers error missing th scope failed - how to fix it

TL;DR

Give your data tables real th header cells with scope attributes: th scope col for column headers, th scope row for row headers. Tables built entirely from td elements fail because nothing identifies the headers. One line of why: screen readers announce each data cell with its headers, and with no th cells there is nothing to announce.

The error, verbatim

{
  "id": "table-headers",
  "impact": "serious",
  "help": "Tables should have identifiable headers",
  "nodes": [
    { "target": ["table.data-grid"], "failureSummary": "Fix any of the following: Table does not have headers with scope or headers attributes" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules table-headers --save axe-thead.json

Expected: Violations array contains table header failures with the table selectors.

Step 2: Inspect the table markup

curl -s https://example.com | rg -o 'table' | wc -l

Expected: Confirms tables exist in the served HTML; view source to see which ones lack th cells.

Step 3: Convert header rows to th with scope

rg -n --glob '*.{jsx,tsx,vue,html}' 'table' src/components | head -15

Expected: Points at the table components to fix.

Step 4: Re-scan

npx @axe-core/cli https://example.com --rules table-headers,scope-attr-valid,td-headers-attr

Expected: Exit code 0 on all three. Screen reader table navigation announces headers for each cell.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (table header rules, WCAG 1.3.1). Covers the th and scope family of table checks. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

table does not have headers axe

The failureSummary wording, same fix.

data table missing th elements

Practitioner phrasing: tables built from divs or td-only markup.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

Data tables rendered from JSON often map every cell to a td, including the header row, because it is one code path. CSS grid div tables skip th entirely since there is no table element. Axe requires identifiable headers via th with scope or headers attributes. Layout tables (used for positioning) should carry role presentation instead, but real data tables need real headers. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• Layout tables are not data tables: give them role presentation rather than th headers.
• Div-based grids need role table, row, columnheader, and rowheader to be tables at all.
• Empty th cells are worse than missing ones for some screen readers, keep header text meaningful.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

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