Hreflang Error Fixes: Getting Every Locale Cluster Right
If your site has versions of the same page for different languages or countries, hreflang annotations tell Google which version belongs to which audience, so a searcher in France is shown the French page and a searcher in Ireland the Irish one.
The annotations are easy to get subtly wrong, and mistakes do not produce error pages; Google simply ignores the parts it cannot trust. The Hreflang Checker follows each cluster of locale pages and validates return tags, language codes, x-default, sitemap consistency, target reachability and canonical alignment. This page explains each error and links to the guide that fixes it.
How a hreflang cluster works
Hreflang works on groups of pages, usually called clusters. Every page in the cluster lists every version, including itself, with the language, and optionally the region, it serves. Here is a complete cluster for a page with British, Irish and French versions and a fallback:
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/">
<link rel="alternate" hreflang="en-IE" href="https://example.com/ie/pricing/">
<link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/tarifs/">
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/">Exactly the same four lines go in the head of all four pages. That repetition is the point: Google only trusts a link between two pages when both pages confirm it. If the French page lists the British page but the British page does not list the French one, Google may ignore the annotation between them.
Four rules follow from this, and nearly every error the checker reports breaks one of them:
- Reciprocity. If A names B, B must name A.
- Self-reference. Each page names itself as well as the others.
- Valid codes. Each value is a real language code, optionally followed by a real region code.
- Indexable targets. Every address in the cluster returns a working page that can be indexed and is its own canonical.
Hreflang is a signal, not a command. It helps Google choose between versions it has already decided to index; it does not force a page into the index, and it does not tell Google what language a page is in. Google works that out from the content itself.
The fix guides, error by error
Each guide explains one error the checker reports: how it breaks the cluster, how to find every instance, how to fix it and how to stop it coming back.
Errors in the structure of the cluster
Fixing missing return tags covers reciprocity, how to audit it across thousands of pages, and generating annotations from one source so pairs cannot fall out of step. Adding missing self-referencing hreflang covers why each page must list itself, one of the most frequent reasons a cluster is not honoured. Adding a missing x-default covers the fallback for visitors who match none of your locales, and whether it should point to a language picker or to an international English page.
Errors in the values
Fixing invalid language codes
covers the ISO standards behind the codes and the usual slips, such as en-UK for en-GB,
or a country code used where a language code belongs.
Errors caused by other signals
Fixing hreflang and canonical
conflicts covers the case where locale pages name one another as canonical, which tells Google they
are duplicates and undermines the whole cluster. Fixing
sitemap and HTML hreflang mismatches covers annotations declared in two places that disagree, and
how to choose one source to maintain. Fixing
hreflang pointing at 404s or redirects covers targets left behind after deletions, launches and migrations,
and automated checks that catch them. Fixing
blocked or noindexed hreflang targets covers targets that robots.txt blocks or that carry noindex,
which Google cannot use.
By platform
Hreflang in WordPress covers WPML, Polylang and TranslatePress, clashes with SEO plugins, and multisite versus a single site with a translation plugin. Hreflang in Shopify covers the annotations Shopify Markets generates, country domains versus subfolders, and errors that appear when a new market is launched. Hreflang in Next.js and Nuxt covers generating annotations from the i18n routing configuration and adding them through each framework's head or metadata system.
Which errors to fix first
Some errors invalidate a whole cluster; others only weaken one link in it. Fix the structural ones first, because a perfect language code is no help on a page Google cannot use.
- Canonical conflicts. If locale pages point their canonicals at one another, Google treats them as copies of one page and the hreflang has nothing to work with.
- Blocked, noindexed, broken or redirecting targets. A target Google cannot index cannot be shown to anyone, so every annotation pointing at it is wasted.
- Missing return tags and self-references. These are the most common errors and the most damaging to a cluster that is otherwise correct.
- Invalid codes. An unrecognised value is ignored, so that locale is effectively missing from the cluster.
- Sitemap and HTML disagreements. Resolve them by choosing one source and removing the other.
- A missing x-default. Recommended rather than required, but it gives you a say over what visitors outside your target markets see.
Valid codes, and the ones that look right but are not
A hreflang value is a language code from ISO 639-1, optionally followed by a hyphen and a region code from ISO 3166-1 alpha-2. A region on its own is not valid. Case does not matter, but the usual style is lower-case language and upper-case region. Many invalid values are country codes used by mistake, and several of them happen to be real codes for a different language.
| Written as | Problem | Correct value |
|---|---|---|
en-UK | The ISO code for the United Kingdom is GB | en-GB |
uk for a UK page | uk is Ukrainian | en-GB |
gb | A country used as a language | en-GB |
jp | Country code, not language | ja or ja-JP |
cn | Country code, not language | zh-CN, or zh-Hans
for Simplified script |
se for Sweden | se is Northern Sami | sv or sv-SE |
dk | Country code, not language | da or da-DK |
gr | Country code, not language | el or el-GR |
en-EU | The EU is not a region code accepted for hreflang | One value
per country, or plain en |
es-LA | Not a country code | One value per country, or plain es |
Use a region only when the content really differs by country, for example prices in euros for Ireland
and pounds for the UK. If you have one English page for everyone, plain en is clearer than
listing it several times under different regions.
HTML, HTTP header or sitemap: choosing where to declare
Google accepts hreflang in three places, and treats them as equivalent:
- Link tags in the HTML head, as in the example above. Simple to check with View Source, but every page grows as you add locales.
- A
LinkHTTP header, the only option for files that have no HTML head, such as PDFs. - The XML sitemap, using
xhtml:linkentries under each address. It keeps the page HTML small and is easier to generate centrally on large sites.
A sitemap entry for the British pricing page looks like this, and a matching entry is needed for every other version:
<url>
<loc>https://example.com/uk/pricing/</loc>
<xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/"/>
<xhtml:link rel="alternate" hreflang="en-IE" href="https://example.com/ie/pricing/"/>
<xhtml:link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/tarifs/"/>
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
</url>The sitemap's opening urlset element must declare the xhtml namespace for
these entries to be read. Using two methods at once is allowed, but it doubles the maintenance and creates
the risk the checker flags as a mismatch: one source updated, the other forgotten. For most sites the
better choice is one method, generated automatically from the same list of locales and addresses the
site uses for its menus and language switcher.
A sensible order of work
- Write down your locale plan: every language and country you serve, and the address pattern for each.
- Run the Hreflang Checker on the main page of each locale and let it follow the cluster.
- Fix canonicals so that every locale page is its own canonical.
- Remove or repair targets that are blocked, noindexed, redirected or missing.
- Choose one declaration method and generate the full cluster, with self-references and return tags, from a single source.
- Correct any invalid codes and add x-default.
- Run the checker again, and add it to your launch checklist for new markets and URL changes.
For the full reference, read the Hreflang Guide, see a finished report in the example report, or start with the beginner tutorial if hreflang is new to you.
1. Do I need hreflang if my site is only in English?
Usually not. Hreflang is for sites with more than one version of the same page for different languages or regions. A single English site serving everyone does not need it. It becomes useful if you run separate English pages for different countries, such as the UK, Ireland and Australia, with different prices, spelling or delivery details, because those pages are otherwise very similar and Google needs help deciding which one to show to a searcher in each country.
2. What happens if hreflang return tags are missing?
Google only trusts a hreflang link between two pages when both pages confirm it. If the French page lists the British page but the British page does not list the French one, Google may ignore the annotation between them. The result is that searchers can be shown the wrong version, for example the British page in France. The fix is to make every page in the cluster list every version, including itself, ideally generated automatically from one list of locales.
3. Is en-UK a valid hreflang code?
No. Hreflang uses ISO 3166-1 alpha-2 codes for regions, and the code for the United Kingdom is GB, so the correct value is en-GB. A value of en-UK is not recognised, which means that version is effectively missing from the cluster. A related trap is using uk on its own, which is the language code for Ukrainian. The Hreflang Checker flags invalid codes, and the same GB rule applies to the lang attribute and to og:locale.
4. What should x-default point to?
It should point to the page you want shown to searchers who do not match any of the languages or regions in the cluster. On many sites that is a language or country selection page. On others it is an international English version, or the main version of the page for the biggest market. The x-default page should itself be a working, indexable page and should be listed in the same cluster on every page, just like the other versions.
5. Should each language version have its own canonical?
Yes. Every locale page should use a canonical tag pointing to its own address. If the French and German pages point their canonicals at the English page, you are telling Google that they are duplicates of the English page, which contradicts the hreflang that says they are alternatives for different audiences. Google tends to follow the canonical, so the translated pages may drop out of the index and the hreflang cluster stops working.
6. Is it better to put hreflang in the sitemap or in the HTML?
Google treats both as equivalent, so choose the one you can keep accurate. HTML link tags are easy to see and check on each page, which suits small sites. A sitemap keeps pages lighter and is easier to generate centrally, which suits large sites with many locales. Avoid maintaining both by hand, because they tend to drift apart and send conflicting signals. Whichever you choose, generate it from the same list the site uses for its language switcher.
7. Does hreflang help my pages rank higher in other countries?
Not in the sense of lifting rankings. Hreflang helps Google choose which of your existing versions to show in each country or language, so the right page appears where you already have visibility. It does not replace the work of earning rankings in a new market, such as translated content written for local searchers, local links and relevant details like currency and delivery. Think of it as routing traffic to the right page rather than creating more of it.
The Hreflang Checker follows each cluster of locale pages and validates return tags, language codes, x-default, sitemap consistency, target reachability and canonical alignment, with the guide that fixes each error.
Run the Hreflang Checker →