Table Headers Must Reference Valid IDs

What this check actually flags

HTML gives you two mechanisms to tell machines which header a data cell belongs to. The simple one is scope on the <th> ("this header covers its column" or "its row"). The heavy-duty one is the headers attribute: each <td> carries a space-separated list of IDs, and each ID must match a <th> elsewhere in the same table.

<th id="q1">Q1</th> ...
<td headers="q1 revenue">$1.2M</td>

This check (it mirrors the axe-core rule td-headers-attr) fails when that contract breaks: the headers value references an ID that does not exist in the table, exists only outside the table, is duplicated so the reference is ambiguous, or points at a plain <td> that is not acting as a header. The failure modes are painfully mundane. A column gets renamed and the id changes but the headers strings do not. A CMS migration strips id attributes for "clean markup". Two tables on one page reuse id="total". A developer separates IDs with commas instead of spaces. Every one of those ships without a visual glitch, because headers changes nothing about rendering.

Why it matters beyond the checkbox

Screen reader navigation depends on it. A sighted user reads a table by glancing up the column and across the row. A screen reader user gets that context because the software announces the associated headers as they move cell by cell: "Q1, Revenue, 1.2 million dollars". When headers references a dead ID, that announcement degrades to a bare number floating in space. In a pricing table or a spec comparison, that is the difference between usable and useless. This lands under WCAG 1.3.1, Info and Relationships, at Level A, the tier legal accessibility complaints usually cite.

Broken associations are worse than none. Here is my actual opinion after cleaning this up on several enterprise sites: a table with no headers attributes and decent structure still works, because screen readers fall back to inferring header relationships from position. A table with broken headers attributes can actively override that inference with garbage. Half-maintained explicit markup loses to no explicit markup. If your team will not maintain the ID plumbing, rip it out and use scope.

Machine readability is the SEO angle. Search engines parse tables to understand structured data on a page and to source table-style rich results; AI crawlers chew the same markup into training and answer material. Header-to-cell association is exactly the relationship a parser needs to turn your table into usable facts ("the price of Plan B is $49"). Valid, unambiguous IDs keep that extraction deterministic. Duplicate IDs, meanwhile, are invalid HTML document-wide and can break more than tables: fragment links, label associations, and your own JavaScript all key off ID uniqueness.

How the reference chain breaks

How to detect it at scale

• axe DevTools / Lighthouse: both run td-headers-attr and report the exact offending cells per page. Lighthouse's accessibility category catches it in CI if you already run it there.
• Screaming Frog: two Custom Extractions, //td/@headers | //th/@headers and //th/@id, crawled site-wide, then a spreadsheet pass to find tokens with no matching ID. On sites with lots of editorial tables this is the only realistic way to inventory the damage and trace it to templates or specific authors.
• W3C Nu HTML Checker: reports headers values that do not reference a th in the same table, plus duplicate IDs, which are frequently the root cause.
• Console spot check: on any page, loop through document.querySelectorAll("[headers]"), split each value on whitespace, and test every token with table.querySelector("th#" + CSS.escape(token)) against the cell's closest table. Rendered-DOM truth, which matters when tables are built by JavaScript.
• A screen reader, honestly. Ten minutes with VoiceOver or NVDA on your most important data table tells you things no crawler will, like headers that resolve but are worded uselessly.

How to fix it, step by step

1. Triage: does this table need headers/id at all? One header row, maybe one header column, no merged cells: that is a simple table. Delete the headers attributes and use scope="col" and scope="row" on the <th>s. Less markup, nothing to go stale. This resolves most flagged tables I encounter.
2. For genuinely complex tables, rebuild the map. Multi-level column headers, merged cells, or headers mid-table justify the full mechanism. Give every <th> a stable, descriptive, table-scoped ID (id="pricing-q1" beats id="c2"), then set each <td>'s headers to the complete set of headers that apply, space separated.
3. Kill duplicate IDs. IDs are unique per document, not per table. Prefix them with a table identifier if the page hosts several tables.
4. Point only at th elements. If a referenced cell is conceptually a header but marked up as <td>, change it to <th> rather than referencing a data cell.
5. Fix the source, not the output. If tables come from a CMS component, a markdown pipeline, or a JavaScript grid, patch the generator so the id/headers pairing is emitted programmatically and cannot drift.
6. Re-verify. Re-run axe on the fixed templates and re-crawl the extraction. Then walk one complex table with a screen reader to confirm the announcements actually make sense.

Reference: choosing the right association method

What good looks like

Simple tables carry scope and nothing else. The few genuinely complex tables carry a complete, current id-to-headers map where every token resolves to a <th> in its own table, IDs are unique across each page, and the whole thing is emitted by a template rather than maintained by hand. axe returns zero td-headers-attr violations, the validator finds no duplicate IDs, and a screen reader walking your gnarliest comparison grid announces sensible context at every cell. Get there once, wire the axe check into CI, and this issue stays dead.

FAQ