axe-core page-has-heading-one error missing h1

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