axe-core landmark-one-main missing main landmark failed

axe-core landmark-one-main missing main landmark failed - how to fix it

TL;DR

Wrap the primary page content in a main element (or one element with role main). There must be exactly one. One line of why: screen reader users jump straight to the main landmark to skip navigation, and with no main landmark that shortcut goes nowhere.

The error, verbatim

{
  "id": "landmark-one-main",
  "impact": "moderate",
  "help": "Document should have one main landmark",
  "nodes": [
    { "target": ["html"], "failureSummary": "Fix any of the following: Document does not have a main landmark" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules landmark-one-main --save axe-main.json

Expected: Violations array contains landmark-one-main targeting html.

Step 2: Find your page shell

rg -n --glob '*.{jsx,tsx,vue}' 'className=.content|id=.content|id=.app' src | head -10

Expected: Points at the layout component wrapping page content.

Step 3: Wrap the content in main and re-scan

npx @axe-core/cli https://example.com --rules landmark-one-main,landmark-no-duplicate-banner,region

Expected: Exit code 0 on all three. Screen reader landmark navigation now lists exactly one main.

Step 4: 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 landmark-one-main, WCAG 1.3.1 / 2.4.1). Check the sibling region rule too, content outside landmarks fails separately. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

document does not have a main landmark

The failureSummary wording, same one-wrapper fix.

axe page needs main landmark element

Practitioner phrasing, also covers SPAs that render content into a bare div.

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

SPA root components usually render header, content div, and footer as siblings with no landmark roles, so the page has zero main landmarks. Axe requires exactly one main landmark per document. A second common shape: the marketing site has main but the app shell (or an embedded widget) adds another, which trips the sibling rule landmark-no-duplicate-main instead. 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

• Exactly one main per document, two mains fail a different rule, merge or demote the extra one.
• In SPAs the main element must wrap the routed content and persist across route changes, do not remount it per route.
• If a third-party script injects its own main, wrap your app so yours is the document-level one and report the widget upstream.
• 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/pstTnBqM0LifrFcRrL_JHsuw