Fix guides · SEO
How to fix “Document doesn't have a valid hreflang”
hreflang tags tell search engines which language or country each version of a page is for. Invalid codes mean the wrong version shows in search results. How to fix them.
- Time to fix
- 15–45 minutes
- Skill needed
- Copy and paste
- Who notices
- Visitors searching in other languages or countries
Why it matters
If your site has versions in several languages or for several countries, hreflang links tell search engines which is which, so a visitor in Canada searching in French sees your French-Canadian page.
Lighthouse checks the language codes. An invalid one (en_US instead of en-US, uk for the United Kingdom instead of en-GB, a made-up code) makes search engines ignore that link.
“Each version of a page must link to all other versions, including itself. Otherwise, search engines may ignore the hreflang links or interpret them incorrectly.”
Before you start
- Use a language code, optionally followed by a hyphen and a country code: en, en-GB, fr-CA, es-419. Use x-default for a language picker or fallback page.
- Every version lists every version, including itself, with full URLs.
- Use one source of hreflang tags. Two tools adding them (a theme and an app, or a plugin and a CDN) create conflicts.
Fix it on your platform
Shopify
- If you use Shopify Markets, Shopify adds hreflang tags automatically through content_for_header and keeps them in sync with your markets and canonical URLs.
- If your theme or an app also outputs hreflang tags, keep only one source. To turn off Shopify's, go to Online Store → Preferences and turn off Automatic hreflang tags in the Social sharing and SEO section.
WordPress
- hreflang tags come from your multilingual plugin. Check its language settings use valid codes (en-GB, not en_GB), and that you don't have a second plugin adding them too.
Webflow
- With Webflow Localize, hreflang tags are generated for you. Check each locale's language and country in Localize panel → Locales, and the hreflang options in Localize panel → SEO.
Wix
- With Wix Multilingual, check each language's settings and region. Remove any hreflang tags you added by hand in Custom Code or Additional Tags.
Squarespace
- If you added hreflang tags through code injection or a translation service, correct their language codes there, and make sure only one source adds them.
Next.js
- Set alternates.languages in each page's metadata with valid codes and absolute URLs.
alternates: {
canonical: "https://example.com/en/shoes",
languages: {
"en-US": "https://example.com/en/shoes",
"fr-CA": "https://example.com/fr-ca/chaussures",
"x-default": "https://example.com/en/shoes",
},
},Any other site
- Add one link per version to every version's <head>.
<link rel="alternate" hreflang="en-US" href="https://example.com/en/shoes">
<link rel="alternate" hreflang="fr-CA" href="https://example.com/fr-ca/chaussures">
<link rel="alternate" hreflang="x-default" href="https://example.com/en/shoes">Check that it's fixed
- View the page source and check every hreflang value is a valid code.
- Re-run your StudioLNC audit: the issue should be gone.
Find every issue like this on your site
Free audit of performance, accessibility, SEO and security, with fixes for your platform.