axe-core empty-heading error empty heading tag failed scan

Not specified by the original author.

axe-core empty-heading error empty heading tag failed scan - how to fix it

TL;DR

An empty [h2][/h2] pollutes the heading outline that screen reader users navigate by, and it usually means a CMS field rendered nothing or a component left a heading shell behind. Either give the heading real text, or remove the heading element entirely. Do not leave the empty heading in place with aria-hidden; remove the dead element.

Empty headings are a canary for template bugs. A CMS that renders [h2][/h2] when the subtitle field is empty is also likely rendering empty paragraphs, empty list items, and broken landmarks. When you find one empty heading, scan the same template for its siblings: the heading is rarely the only empty element.

The verbatim error looks like this:

axe-core 4.x
Rule: empty-heading (minor)
"Empty heading"

Element: [h2][/h2]
  Heading contains no discernible text.

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/blog --rules empty-heading

Expected: each empty heading is listed with its level.

2. Find why it is empty: a CMS field with no value, a component rendering a heading wrapper unconditionally, or a heading cleared by JavaScript after load. The fix depends on the cause.
3. Fix at the source: if the content is missing, remove the heading from the template when the field is empty:

(only render the heading when the subtitle exists)
[if subtitle][h2][subtitle][/h2][/if]

If the heading should have content, add it. Never paper over with aria-hidden on a real heading.

4. Re-run the focused scan. Expected output: 0 violations for empty-heading.
5. Run heading-order alongside to make sure removing or filling the heading did not create a skipped level:

npx @axe-core/cli https://example.com/blog --rules empty-heading,heading-order,page-has-heading-one

6. Find the template or component responsible. Empty headings come from conditional rendering done wrong: the heading tags render unconditionally while the content is conditional. Move the condition to wrap the whole heading element.
7. Scan the same pages for other empty elements the same bug produces:

npx @axe-core/cli https://example.com/blog --rules empty-heading,empty-table-header

Fix the template once rather than patching pages one by one.

When to use

• Axe flags empty-heading on h1-h6 elements.
• A CMS or template renders heading shells when fields are empty.
• A screen reader heading rotor shows blank entries.

When not to use

• Headings skip levels (h2 followed by h4) (that is heading-order).
• The page has no h1 at all (that is page-has-heading-one).
• The heading has text but it is decorative (remove the heading; do not empty it).

Why it happens

Screen reader users navigate long pages by headings the way sighted users scan visually. Empty headings create dead stops in that navigation and signal sloppy templates. The rule is minor severity, but a page full of empty headings is a strong smell that the template renders structure without content, which usually hides bigger problems.

Content management systems separate structure from content: the template defines where headings go, editors fill in the text. When an editor leaves a field blank, a naive template still emits the heading tags. The result is invisible in visual QA (an empty heading takes no space) and only appears in heading navigation or scans. Headless CMS frontends built with component libraries have the same failure mode.

Edge cases

• Headings filled only by JavaScript after axe runs will flag. Run axe after hydration, or server-render the text.
• A heading containing only whitespace or a non-breaking space still counts as empty.
• Visually-hidden headings with real text pass the rule and are a legitimate technique for section labeling.
• Do not 'fix' by stuffing keywords into the heading; write the heading the section actually needs.
• Rich-text editors sometimes emit [h2][br][/h2] for an 'empty' heading. A [br] is not discernible text; the rule still flags it.
• Anchor links pointing at empty headings (table of contents entries) break too. Validate the TOC against rendered headings.
• Some teams fill empty headings with   to 'fix' the scan. A non-breaking space is not discernible text and the hack fails on re-scan.
• A summary that only contains an [img] with empty alt still fails; the image contributes no discernible text.
• If the disclosure is generated by a CMS accordion block, fix the block template so editors cannot publish a textless summary.
• Voice control users say the summary text to toggle the disclosure; an icon-only summary gives them nothing to say.

Provenance

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

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

Thread query: axe-core empty-heading error empty heading tag failed scan

TL;DR: An empty [h2][/h2] pollutes the heading outline that screen reader users navigate by, and it usually means a CMS field rendered nothing or a component left a heading shell behind. Either give the heading real text, or remove the heading element entirely. Do not leave the empty heading in place with aria-hidden; remove the dead element.

Not specified by the original author.

axe-core heading-order error skipped heading level bug - how to fix it

TL;DR

Fix the heading outline so levels only increase by one: h1 then h2, then h3, never h1 straight to h3. Restyle with CSS classes instead of picking a heading level for its looks. One line of why: screen reader users navigate by heading level, and a skipped level makes the outline lie about the page structure.

The error, verbatim

{
  "id": "heading-order",
  "impact": "moderate",
  "help": "Heading levels should only increase by one",
  "nodes": [
    { "target": ["h4.section-title"], "failureSummary": "Fix any of the following: Heading order invalid" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules heading-order --save axe-head.json

Expected: Violations array contains heading-order with the offending heading selectors.

Step 2: Dump the heading outline

node -e "console.log('use the headingsMap check in axe DevTools or:')"; curl -s https://example.com | rg -o 'h1|h2|h3|h4|h5|h6' | sort | uniq -c | head -10

Expected: Shows the heading sequence so you can spot the skipped level.

Step 3: Find the skipped headings in source

rg -n --glob '*.{jsx,tsx,vue,html}' 'h4|h5|h6' src | head -20

Expected: Shows heading usages to renumber.

Step 4: Fix the levels and re-scan

npx @axe-core/cli https://example.com --rules heading-order

Expected: Exit code 0, 0 violations. The outline now descends one level at a time.

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+ (rule heading-order, WCAG 1.3.1). Pair with page-has-heading-one for a valid outline. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

heading order invalid axe

The failureSummary wording, same fix.

skipped heading level h1 to h3

The classic instance: authors pick h3 because it looks right.

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

Authors choose heading levels by visual size, so an h4 gets used for a subsection that should be an h3, skipping a level. Component libraries hardcode heading levels inside cards and widgets, which then land at the wrong depth on different pages. Axe only checks that increases are by one, decreases can jump freely, so the fix is always about renumbering the too-deep headings. 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

• Decreasing levels can skip freely (h3 back to h1 is fine), only increases must step by one.
• Style with classes, not heading levels: an h3 styled to look like an h4 is correct, an h4 used as a subsection is not.
• Reusable components should accept a heading level prop or use the lowest sensible level.
• 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_o6K7wR2LqmTrbuqC3a65xw

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

Thread query: axe-core heading-order error skipped heading level bug

TL;DR: Fix the heading outline so levels only increase by one: h1 then h2, then h3, never h1 straight to h3. Restyle with CSS classes instead of picking a heading level for its looks. One line of why: screen reader users navigate by heading level, and a skipped level makes the outline lie about the page structure.

Not specified by the original author.

axe-core page-has-heading-one error missing h1 - how to fix it

TL;DR

Add exactly one h1 per page (per document view in SPAs) describing the page. Put it at the top of the main content, not in the logo. One line of why: the h1 is the page's title for screen reader users, and heading navigation starts there.

The error, verbatim

{
  "id": "page-has-heading-one",
  "impact": "moderate",
  "help": "Page should contain a level-one heading",
  "nodes": [
    { "target": ["html"], "failureSummary": "Fix any of the following: Page must have a level-one heading" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules page-has-heading-one --save axe-h1.json

Expected: Violations array contains page-has-heading-one targeting html.

Step 2: Check current headings

npx @axe-core/cli https://example.com --rules page-has-heading-one --stdout | head -5; curl -s https://example.com | rg -o 'h1' | wc -l

Expected: Confirms no h1 exists in the rendered page.

Step 3: Add one h1 per page view

rg -n --glob '*.{jsx,tsx,vue}' 'h2' src/pages | head -10

Expected: Shows page components where the top heading should become or gain an h1.

Step 4: Re-scan

npx @axe-core/cli https://example.com --rules page-has-heading-one,heading-order

Expected: Exit code 0 on both. The page now has one h1 and no skipped levels.

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+ (rule page-has-heading-one, WCAG 1.3.1). Best-practice rule, pair with heading-order for a clean outline. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

page must have a level-one heading

The failureSummary wording, same fix.

axe missing h1 on page

Short phrasing, also covers SPAs where the h1 never updates on route change.

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

Design systems style the logo or hero text as the visual title without using an h1 element, or SPAs render the h1 only on the landing view and forget it on routed views. Axe checks the whole document for at least one h1. Multiple h1s do not fail this rule (that is a manual-review concern), only zero h1s fail. 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

• In SPAs, update the h1 on every route change, a stale h1 from the last page is misleading.
• Do not put the h1 on the site logo in the header, the h1 should describe the page, not the site.
• Visually hidden h1s are fine for the rule and for screen readers, if the design has no visible title.
• 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-sGoWro8-E2pP9CAzGG5w

Resolved from the public thread: https://vectle.com/posts/pst-sGoWro8-E2pP9CAzGG5w

Thread query: axe-core page-has-heading-one error missing h1

TL;DR: Add exactly one h1 per page (per document view in SPAs) describing the page. Put it at the top of the main content, not in the logo. One line of why: the h1 is the page's title for screen reader users, and heading navigation starts there.