axe-core html-has-lang missing lang attribute failed

Not specified by the original author.

axe-core html-has-lang missing lang attribute failed - how to fix it

TL;DR

Add a lang attribute to the html element, like lang en, matching the page's primary language. It is a one-line fix in your document template or root layout. One line of why: screen readers pick pronunciation rules from the page language, and without it they guess, often badly.

The error, verbatim

{
  "id": "html-has-lang",
  "impact": "serious",
  "help": "The html element must have a lang attribute",
  "nodes": [
    { "target": ["html"], "failureSummary": "Fix any of the following: The html element does not have a lang attribute" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules html-has-lang --save axe-lang.json

Expected: Violations array contains html-has-lang with target html.

Step 2: Find where the html element is rendered

rg -n --glob '*.html' 'html lang' src/templates | head; rg -n 'html' src/app/layout.tsx | head -5

Expected: Points at your base template or root layout file. (The search pattern here is illustrative, adjust for your stack.)

Step 3: Check the current value if present

curl -s https://example.com | head -c 400

Expected: Shows the doctype and opening html tag so you can see the missing or wrong lang value.

Step 4: Add lang and re-scan

npx @axe-core/cli https://example.com --rules html-has-lang

Expected: Exit code 0, 0 violations. View source confirms the lang attribute on the html element.

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 html-has-lang, WCAG 3.1.1). Trivially fixable in any framework, same rule in pa11y and lighthouse. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

the html element does not have a lang attribute

The failureSummary wording, same one-line fix.

axe lang attribute missing on html tag

Common phrasing, also covers the html-lang-valid sibling rule for bad values like en_US.

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

Server-rendered templates and SPA index.html shells often ship without a lang attribute because no framework adds one by default. Axe flags the missing attribute on the single html element, so one page failing means every page from the same template fails. A wrong value (like a locale with an underscore) trips the sibling rule html-lang-valid 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

• Pages with mixed languages need lang attributes on the inline sections too, the page-level lang only sets the default.
• Set the value to the actual content language, not the company's home language, a Spanish page marked en is worse than missing.
• Framework root layouts (Next.js app/layout, Nuxt app.vue) are the one place to fix, do not sprinkle lang on divs.
• 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_9wAitr7pBNjKjsIblJMABQ

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

Thread query: axe-core html-has-lang missing lang attribute failed

TL;DR: Add a lang attribute to the html element, like lang en, matching the page's primary language. It is a one-line fix in your document template or root layout. One line of why: screen readers pick pronunciation rules from the page language, and without it they guess, often badly.

Not specified by the original author.

axe-core valid-lang error: invalid language code - how to fix it

TL;DR

This fixes the flagged violation at its source instead of silencing the rule. The lang attribute holds a value that is not a valid language code, so pronunciation rules misfire. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

The error, verbatim

axe-core valid-lang error: invalid language code

Fix it step by step

Step 1

Set lang to a valid BCP 47 code like en, en-US, or fr.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 2

Check for typos like eng or en_US with an underscore; both fail.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 3

If the page mixes languages, put lang on the specific elements that switch language.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 4

Re-run axe to confirm.

Expected: the step completes with no new console errors and the flagged element changes as described.

When to use this skill

• Your scan report lists this exact rule or failure
• You are clearing automated accessibility failures before release or audit
• A CI accessibility gate is red because of this item

When NOT to use this skill

• An empty or missing lang is a different rule (html-has-lang / valid-lang catches malformed values).
• The issue only appears in manual screen-reader testing and no automated rule flags it
• You are doing a full manual WCAG audit; this skill covers one automated check

Compatibility

axe-core 4.8+ (rule valid-lang, WCAG 3.1.1).

Variant phrasings

axe valid-lang: invalid language code

Same underlying issue and the same fix. Searchers phrase it different ways; the remediation does not change.

Why it happens

The lang attribute holds a value that is not a valid language code, so pronunciation rules misfire. These violations repeat across pages built from the same templates or components, so fix the shared source once and re-scan the whole site to confirm the fix cleared every instance.

Provenance

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

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

Thread query: axe-core valid-lang error: invalid language code

TL;DR: This fixes the flagged violation at its source instead of silencing the rule. The lang attribute holds a value that is not a valid language code, so pronunciation rules misfire. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

Not specified by the original author.

axe-core html-xml-lang-mismatch error lang xml lang mismatch failed - how to fix it

TL;DR

When the [html] element carries both lang and xml:lang, their base languages must match. This mismatch almost always comes from a copy-pasted XHTML template or a CMS that sets one attribute while the theme sets the other. Pick the page's real language, set both attributes to it (or drop xml:lang entirely on HTML5 pages), and re-run the focused axe rule.

This violation is almost always inherited, not introduced: a layout template, a CMS theme, or a static-site generator default that nobody has touched in years. Fix it in the layout or theme once and every page inherits the correction. If different sections of the site genuinely serve different languages, the per-page lang should come from the content, and xml:lang should be dropped everywhere.

The verbatim error looks like this:

axe-core 4.x
Rule: html-xml-lang-mismatch (moderate)
"HTML elements with lang and xml:lang must have the same base language"

Element: [html lang="en" xml:lang="fr"]
  Base languages differ: "en" vs "fr".

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/ --rules html-xml-lang-mismatch,html-has-lang,html-lang-valid

Expected: the [html] element is flagged for the mismatch.

2. Determine the page's actual language from its content. That is the value both attributes should carry.
3. Fix the attributes. For HTML5, the simplest correct fix is to drop xml:lang:

[html lang="en"]

If you serve true XHTML and need xml:lang, make them match: [html lang="en" xml:lang="en"].

4. Re-run the focused scan. Expected output: 0 violations across the three lang rules.
5. Verify with a screen reader that content is announced in the right language and accent.
6. Find where the attributes are set. Check the base layout, theme header, and any CMS language settings. The mismatch means two systems each set one attribute:

rg -l 'xml:lang' layouts/ themes/ src/

7. After fixing, crawl more than the homepage. Language settings often vary by section or content type, and a homepage-only check misses mismatches on translated or legacy sections.

When to use

• Axe flags html-xml-lang-mismatch on the html element.
• A template migrated from XHTML still carries a stale xml:lang.
• A multilingual CMS sets lang per page while the theme hardcodes xml:lang.

When not to use

• The page has no lang attribute at all (add lang; that is html-has-lang).
• The lang value itself is not a valid code (fix the code; that is html-lang-valid).
• A section of the page is in another language (mark that section with its own lang attribute; do not change the page-level attributes).

Why it happens

Screen readers use the lang attribute to pick pronunciation rules. When lang says English and xml:lang says French, XML-aware tooling and HTML tooling disagree about how to read the page, and the user gets the wrong pronunciation. The mismatch is a leftover from the XHTML era and has no legitimate use on modern HTML pages.

xml:lang is a relic of XHTML, when pages were parsed as XML and the XML language attribute mattered. HTML5 parsing ignores xml:lang entirely, but axe still checks it when present because XML tooling (validators, some assistive tech pipelines) still reads it. The mismatch arises during migrations: the HTML was converted from XHTML, lang was updated over the years, and xml:lang fossilized.

Edge cases

• Only the base language must match: lang="en-US" with xml:lang="en-GB" passes because the base ('en') agrees.
• The rule checks every element carrying both attributes, not just [html], though [html] is the overwhelmingly common case.
• Some static-site generators inject xml:lang via a layout default. Override it in the layout, not on every page.
• After the fix, run html-lang-valid too: a matching but invalid code just moves the failure to the next rule.
• XHTML served as application/xhtml+xml genuinely uses xml:lang, but almost nobody serves true XHTML anymore. Confirm your content type before keeping it.
• hreflang on links is unrelated to this rule. Do not 'fix' the mismatch by touching hreflang annotations.
• Automated translation plugins that rewrite lang per page can reintroduce the mismatch. Pin the fix in the layout, not per page.
• Some teams keep xml:lang 'for the XML sitemap tools'. Sitemap tooling reads hreflang and page content, not xml:lang on the html element.
• After the fix, validate a sample of pages with the W3C validator to confirm no other legacy XHTML attributes linger.
• If your site serves both HTML and XHTML from the same templates, split the layouts; one template cannot serve both correctly.

Provenance

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

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

Thread query: axe-core html-xml-lang-mismatch error lang xml lang mismatch failed

TL;DR: When the [html] element carries both lang and xml:lang, their base languages must match. This mismatch almost always comes from a copy-pasted XHTML template or a CMS that sets one attribute while the theme sets the other. Pick the page's real language, set both attributes to it (or drop xml:lang entirely on HTML5 pages), and re-run the focused axe rule.