How to Fix Hreflang Errors: Complete Guide
Your audit flagged one or more hreflang problems: an invalid or unknown language code, a missing return (reciprocal) link, or a missing x-default. Hreflang tells Google which language and regional version of a page to show which users. When the annotations are malformed, incomplete, or non-reciprocal, Google ignores the whole cluster and falls back to guessing. That causes the wrong-language page to rank, duplicate-content confusion between regional versions, and lost clicks. This guide explains each error code, why it matters, and exactly how to fix it with correct tags and platform-specific steps.
What this means
Hreflang is a set of annotations that map every language and region variant of a page to each other, so a search engine can serve the right one. The audit flagged four distinct failure modes.
hreflang_invalid_code — The value isn't a well-formed hreflang. Hreflang uses an ISO 639-1 language code (like en, de, fr), optionally followed by a hyphen and an ISO 3166-1 Alpha-2 region code (like en-GB, en-US, pt-BR). Common breaks: using an underscore (en_US) instead of a hyphen, reversing the order (us-en instead of en-US), or supplying a region code with no language.
hreflang_unknown_language — The language or region token isn't a real ISO code. Classic cases: en-UK (the correct code for the United Kingdom is en-GB), using cn as the language for Chinese (the language code is zh, so a China-targeted page is zh-CN), or a typo like fi (Finnish) on a page that should be fr (French).
hreflang_missing_return_link — Hreflang must be reciprocal. If page A points to page B, page B must point back to page A. When a variant doesn't link back, Google treats the whole set as untrusted and ignores it. This also fires when a page is missing its self-referencing tag, since each URL must list itself.
hreflang_missing_x_default — There's no x-default entry. x-default is the fallback shown to users whose language or region doesn't match any listed variant (for example, a French speaker landing on a site that only has English, German, and Spanish pages).
Why it matters
Google's rule is strict: if the hreflang cluster is malformed or non-reciprocal, it ignores the annotations entirely and falls back to its own signals to pick a version. That usually means the wrong-language page ranks for a query, or two near-identical regional pages (say en-US and en-GB) compete against each other and split their authority, hurting both.
The most damaging error is the missing return link, because it doesn't just weaken one page. It can invalidate the entire language group. You lose the whole point of the setup: users see content they can't read, bounce, and your regional targeting stops working.
A missing x-default is lower severity but still leaves a gap. Without it, a visitor whose locale matches nothing gets an unpredictable pick instead of your intended landing page, which is often the international English homepage.
For AI answer engines, the impact is subtler but real. Assistants like ChatGPT, Perplexity, and Google's AI Overviews crawl and cite specific URLs. Clean hreflang helps them surface the language-appropriate version when a user asks in a given language, and it prevents duplicate regional URLs from muddying which page is treated as canonical for a topic. Broken hreflang won't block AI crawlers outright, but it removes a strong signal about which variant is authoritative.
How to fix it
- 1
Fix invalid codes and typos first
Correct the format before anything else. Use a lowercase ISO 639-1 language code, and if you target a region, add a hyphen plus an ISO 3166-1 Alpha-2 region code:
en,en-GB,pt-BR,zh-Hant. Replace underscores with hyphens (en_usbecomesen-US), fix reversed order (us-enbecomesen-US), and swap invalid tokens (en-UKbecomesen-GB). Google is not case-sensitive here, but writing the language lowercase and the region uppercase is the convention and avoids human error. Never use a region code with no language. - 2
Add a self-referencing tag to every variant
Each page in the cluster must list itself in its own hreflang set, alongside all its siblings. A page with three language versions carries four link tags on every page: one for each language plus its own self-reference. If your
en-USpage listsde-DEandfr-FRbut forgets to listen-US, the annotation is incomplete and Google may discard it. - 3
Make every link reciprocal
The return-link error is the one that silently kills clusters. If
example.com/us/points toexample.com/de/, thenexample.com/de/must point back toexample.com/us/with the matching hreflang. The cleanest way to guarantee this is to generate one shared block of hreflang tags and inject the identical block into the<head>of every variant. When all pages carry the same complete set, reciprocity is automatic. Every URL must return HTTP 200; a link to a redirect (301) or a 404 breaks the set. - 4
Add exactly one x-default
Add a single
x-defaultentry pointing to your fallback page for unmatched users, commonly the international or English homepage. Only onex-defaultis allowed per cluster; a second one makes Google ignore them. A page that also has a specific hreflang (likeen) can double as thex-default. Just list both entries. - 5
Pick one delivery method and keep it consistent
Deliver hreflang via HTML
<link>tags in the<head>, via the XML sitemap, or via HTTP headers (used for non-HTML files like PDFs). Pick one method per set of URLs; mixing them for the same URLs invites conflicts. HTML head tags are simplest for most sites, while XML sitemap annotations scale better for large sites because you manage the whole map in one file. Always use absolute URLs with protocol and domain, never relative paths. - 6
Re-crawl and validate
After deploying, re-run your audit or a dedicated hreflang tester to confirm every variant is reciprocal, all codes are valid,
x-defaultis present once, and no URL 301s or 404s. In Google Search Console, use URL Inspection to check how Google reads a specific page's alternates. Changes can take a few crawl cycles to register, so re-check after Google recrawls the set.
Example
<!-- Place this SAME block in the <head> of every language variant -->
<link rel="alternate" hreflang="en-US" href="https://example.com/us/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/" />
<link rel="alternate" hreflang="de-DE" href="https://example.com/de/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/us/" />
<!-- Common mistakes this avoids: -->
<!-- WRONG: hreflang="en_US" (underscore instead of hyphen) -->
<!-- WRONG: hreflang="en-UK" (UK is not the ISO code; use GB) -->
<!-- WRONG: hreflang="us-en" (order reversed) -->
<!-- WRONG: relative href="/de/" (must be absolute) -->
<!-- WRONG: two x-default entries, or none at all -->A correct, fully reciprocal hreflang block. This identical block goes in the <head> of all three pages, which guarantees return links and self-references. Note the single x-default.
Platform-specific steps
Yoast SEO core does not output hreflang for translations; it relies on a translation plugin. In practice, use WPML or Polylang, which generate reciprocal hreflang tags (including x-default) across linked translations for you. Confirm the translation plugin's language settings map to real ISO codes. WPML lets you edit the hreflang code per language if the default is wrong, for example changing a bad en-UK to en-GB. RankMath also defers to the translation plugin for multilingual hreflang. After enabling, view source on two variants and confirm each lists the other plus itself.
Shopify outputs hreflang automatically once you add languages under Settings > Languages (using Translate & Adapt or a third-party translation app) and publish them. The theme's theme.liquid must include {{ content_for_header }} in the <head>, which is where Shopify injects the tags; most themes already do. If tags are missing, check that languages are published (not just added) and that the theme hasn't stripped the header output. For multi-country setups, Shopify Markets generates region-specific hreflang, so verify the generated codes in view-source rather than assuming.
Wix generates hreflang automatically when you set up Wix Multilingual and add languages. You don't hand-edit tags, but verify the codes in view-source and confirm x-default resolves to your main language. Squarespace has no native multilingual hreflang system. If you run separate language pages or sites, you typically inject <link rel="alternate" hreflang=...> tags via Settings > Advanced > Code Injection (per-page header), which means you are responsible for keeping them reciprocal across every page.
For static or framework-rendered sites, generate the hreflang set from a single source of truth (a locale config) and render the identical <link> block into every page's head. That is the reliable way to guarantee reciprocity. In the Next.js App Router, return them from the alternates.languages field in generateMetadata, including an 'x-default' key, and the framework emits the link tags. Always output absolute URLs. For large sites, prefer generating the annotations in the XML sitemap so you maintain the entire cluster in one file instead of per-page.
Frequently asked
en-GB is correct; en-UK is invalid. Hreflang region codes follow the ISO 3166-1 Alpha-2 standard, where the United Kingdom's code is GB, not UK. UK is exceptionally reserved in that standard but is not the assigned country code, so search engines treat en-UK as an unknown region and ignore that annotation. Always use en-GB.
Only if you have genuinely distinct regional versions, such as a US price page and a UK price page with different currency, spelling, or shipping info. In that case use en-US and en-GB to stop them competing as duplicates. If you have a single English page for everyone, you don't need hreflang; it signals variants, not a single version.
No, it's optional, but it's strongly recommended. Without x-default, users whose language and region match none of your listed variants get an unpredictable pick from Google. Adding one x-default, usually your international or English homepage, gives those users a deliberate landing page. Only ever include one x-default per cluster; a second one causes Google to ignore all of them.
The most common cause is missing return links: if page A points to B but B doesn't point back to A, Google discards the annotations. Other frequent causes are URLs that 301-redirect or 404 instead of returning 200, missing self-referencing tags, relative instead of absolute URLs, hreflang on noindexed pages, or invalid codes. Fix reciprocity first, then confirm every listed URL returns a clean 200.
Any of the three works and Google treats them equally, but use only one method per set of URLs to avoid conflicts. HTML head <link> tags are easiest for small to mid-size sites. XML sitemap annotations scale better for large sites because the whole cluster lives in one file. HTTP headers are mainly for non-HTML resources like PDFs where there's no head to put tags in.
Does your site have this issue?
Run a free, AI-powered audit and we’ll flag this and 150+ other checks in about a minute. No signup.