Hreflang Errors: How to Find and Fix Every Common Mistake

Hreflang annotations tell Google which URL serves which language or region, so that someone searching in German from Switzerland is pointed to your Swiss German page instead of the version for Germany. When the annotations are wrong, nothing on your site looks broken. Google simply ignores the pairs it cannot confirm, and the wrong version keeps reaching the wrong audience.

Most hreflang problems come from a short list of mistakes: missing return links, codes Google does not accept, alternates that redirect or name a different canonical, and sets that forget to list the page itself. Each one is easy to fix once you can see it, and surprisingly hard to spot by reading templates.

This guide explains how Google reads hreflang according to its own documentation, walks through every common error with the exact fix, and ends with a repeatable audit you can run after each release. Examples use example.com unless they come from a real, dated test.

What hreflang does, and what it does not

Google describes hreflang as the way to tell it about localized variations of the same content, so Google Search can point users to the most appropriate version by language or region. Google may find alternate versions without help, but recommends marking them explicitly. The documented use cases are a fully translated site, one language with small regional variations (for example English for the US, the UK and Ireland), and pages where only the navigation and footer are translated.

Two things hreflang does not do are worth knowing before you start debugging. First, Google states that it does not use hreflang or the HTML lang attribute to detect the language of a page; its guide to multilingual sites says it uses the visible content instead. Second, translations are not duplicates: Google considers localized versions duplicates only if the main content remains untranslated.

The lang attribute vs hreflang

The two are often confused because both carry language codes. The lang attribute declares the language of the content on the page itself, using a BCP 47 tag. According to MDN, WCAG success criterion 3.1.1 requires the page language to be programmatically determinable, mainly so assistive technology such as screen readers can use the right pronunciation. Hreflang points to the other versions of the page.

Use both and keep them consistent. A page that annotates itself as fr while declaring lang="en" will not confuse Google's language detection, but it usually reveals a template that labels the wrong language somewhere.

Three ways to declare hreflang

Google accepts annotations in HTML, in HTTP headers and in XML sitemaps, and says the three methods are equivalent. You can use all three at once, but Google notes there is no benefit in Search and that maintaining three implementations is much harder. Whatever you choose, the same rules apply: each version lists itself and every other version, alternate URLs are fully qualified including https://, and alternates may live on other domains.

HTML link elements

Add one link element per version, including the current page, inside a well-formed head. The set is identical on every version. Google also asks you not to combine hreflang with other attributes such as media in a single link tag.

<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/pricing/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/pricing/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/preise/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/" />

HTTP Link header

Headers are the only option for files without an HTML head, such as PDFs. Each URL sits in angle brackets, entries are separated by commas, and every version returns the same header.

Link: <https://example.com/guide.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/de-ch/guide.pdf>; rel="alternate"; hreflang="de-CH",
      <https://example.com/de/guide.pdf>; rel="alternate"; hreflang="de"

XML sitemap

In a sitemap, each version gets its own url entry, and every entry lists all variants, itself included, as xhtml:link children. Declare the xhtml namespace; the child elements do not count toward the sitemap URL limit. For everything else about sitemap format, see our XML sitemap best practices.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/de/preise/</loc>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/"/>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/en-us/pricing/"/>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/pricing/"/>
  </url>
</urlset>

Language and region codes Google accepts

An hreflang value is a language code in ISO 639-1 format, optionally followed by a hyphen and a region code in ISO 3166-1 alpha-2 format. Google supports only codes listed in those two standards, so BCP 47 forms such as es-419 do not work. Values are case-insensitive, although uppercase regions (en-GB) follow the ISO convention. For scripts, Google derives the script from the region (zh-TW) or accepts an explicit ISO 15924 script such as zh-Hant or zh-Hans-US.

Return links and self-references: the rule behind most errors

Missing return links head Google's own list of the most common hreflang mistakes. If page X lists page Y as an alternate, page Y must list page X. When two pages do not both point to each other, Google ignores the annotations, a safeguard that stops another site from declaring itself an alternate of yours. The same rules require every version to list itself, so a complete set on each page contains the page's own URL plus all its siblings.

1. example.com/de/preise/Lists de (itself), en-US, en-GB and x-default
2. example.com/en-gb/pricing/Must list de/preise/ back, plus itself and the others
3. Pair confirmedBoth directions exist, so Google can use the annotation

On very large sites, a complete set on every page can become hard to maintain. Google says you may omit some languages on some pages and it will still process the pairs that point to each other, but it stresses linking newly added language versions bidirectionally with the original or dominant language first. In practice, generating every set from one table of equivalent URLs avoids most of these gaps.

x-default: the fallback for unmatched languages

The reserved x-default value names the page for users whose language settings match none of your versions. It is optional. Google says you can point it to any page, but it was designed for language selector pages and works best with them, for example a country chooser or a home page that redirects visitors by language. It needs no language code because the page serves everyone who is unmatched.

Treat x-default as one more entry in the set, so it appears on every version, not only on the selector page. A cluster where some pages declare x-default and others do not is not the identical set Google describes for the HTML method.

Canonicals, redirects and noindex

Hreflang is processed alongside canonicalization, and the two must tell the same story. Google's canonicalization guide asks you to specify a canonical page in the same language when you use hreflang, or the best substitute language if no same-language canonical exists. It also says rel="canonical" links that carry an hreflang attribute are ignored for canonicalization, and that Google prefers URLs that are part of hreflang clusters when it chooses canonicals.

For same-language regional duplicates, such as German content on both example.de and example.com/de/, Google recommends picking a preferred version and using rel="canonical" together with hreflang so the right regional URL is served. For the wider topic of duplicates, see duplicate content and canonicals.

Two of these points need a word of explanation. Google's documentation does not describe how it treats an annotation that points to a redirect; our recommendation to annotate final URLs is Backlnk's interpretation, because the redirecting URL itself cannot return the pair. If you are cleaning up redirects, our guide to 301 vs 302 redirects covers the codes. Automatic redirects are documented: Google advises against redirecting users by assumed language and notes that Googlebot usually crawls from the US without an Accept-Language header, so it may never see versions that are only reachable through redirects. Finally, noindex keeps a page out of search results, so an alternate marked noindex cannot be shown to its audience. If a version is missing from Google, start with why a page is not indexed.

A step-by-step hreflang audit

Run this audit when you launch a language, change templates or migrate URLs. It goes from structure to detail, so you fix the causes before the symptoms.

1. List every cluster. For each page, write down all its language and regional equivalents in one table. This table becomes the single source for generating annotations.

2. Pick one method. Choose HTML, headers or the sitemap, and remove partial copies of the other methods so sources cannot disagree.

3. Validate every code. Check each value against ISO 639-1 and ISO 3166-1 alpha-2, and replace en-UK, underscores and region-only values.

4. Check each set. Every version should list itself and every sibling with absolute https URLs, and the set should be the same on all versions.

5. Confirm return links pair by pair. For every annotation from X to Y, confirm that Y lists X. Missing returns head Google's list of common mistakes.

6. Check each alternate URL. It should answer 200 without redirecting, declare a self-referencing or same-language canonical, and carry no noindex.

7. Decide on x-default. If you have a language selector or a default version, add x-default to every set.

8. Re-check after deployment. Annotations break silently when templates or URL patterns change, so repeat the check after releases.

Check your hreflang with Backlnk's Hreflang Validator

The Hreflang Validator starts from one URL and follows hreflang alternates first, then ordinary links, within a bounded crawl of up to 40 pages on the same site. It collects annotations from HTML link elements, HTTP Link headers and XML sitemaps, groups the pages into language clusters and checks codes against ISO 639-1 and ISO 3166-1 alpha-2, self-references, x-default, return links between every pair, and whether each alternate resolves, is canonical and is indexable. It also flags valid codes that are often a mistaken country code, disagreements between annotation sources and lang attributes that differ from a page's own annotation.

Two limits are worth knowing: a bounded crawl sees only the alternates it reaches, so very large international sites need several runs, and the report lists every alternate it could not check instead of guessing.

We ran the validator on mozilla.org/en-US/ on October 31, 2026, with a 10-page budget. The report found 869 annotations on the 10 pages it fetched, all in HTML link elements, using 87 distinct hreflang values for 77 URLs in one cluster. All values were well-formed, all 10 pages referenced themselves, all 90 checked pairs had return links, and every checked alternate answered directly with a self-referencing canonical and no noindex. Another 669 pairs were not checked because of the page budget.

The report also listed five values as "often a mistaken country code": be, ca, my, si and uk. On Mozilla's site they are intended languages (Belarusian, Catalan, Burmese, Sinhala and Ukrainian), and the pages' own lang attributes matched, for example lang="be" on /be/. That is why the check is informational: only you know whether uk means Ukrainian or a mistaken United Kingdom. The raw annotations showed two more details. Mozilla maps both en and en-US to /en-US/, the generic-fallback pattern Google describes, and the /en-US/ page listed 86 annotations while the other nine checked pages listed 87; the difference was the x-default entry pointing to https://www.mozilla.org/. Small inconsistencies like this are exactly what a pairwise check surfaces and a template review misses.

Hreflang is also part of the free full website audit, which Backlnk delivers by email.

Next step

Pick your most important page that exists in several languages and run it through the Hreflang Validator. Fix missing return links and invalid codes first, because Google ignores those annotations entirely, then align canonicals and remove redirecting alternates. Re-run the check after your next release to confirm the set stayed intact.