You added a new language version to your site, and almost immediately hreflang problems appeared: the new language is not indexed, the wrong version shows in search, or Google Search Console reports missing return links. Hreflang is unforgiving — a single missing reference can break the whole cluster. This guide explains the most common hreflang errors after adding a language, how to find them, and how to fix them without breaking the existing versions.
What hreflang does and why it breaks easily
Hreflang tells search engines which language and regional version of a page to show to which user. It is not a ranking factor by itself, but it helps search engines serve the right version, which improves click-through rate and reduces duplicate content issues across language versions.
Hreflang is implemented as a set of link elements in HTML, HTTP headers, or XML sitemaps. Each page in a language cluster must reference all other pages in the same cluster, including itself. This is called the return link requirement. If one page is missing a reference, the cluster is considered incomplete, and search engines may ignore the entire cluster.
When you add a new language, you create a new page that must be added to every existing language page as a reference. If you forget even one, the cluster breaks. This is why hreflang errors spike right after adding a language.
Error 1: missing return links
The most common hreflang error is a missing return link. If the English page references the German page, but the German page does not reference the English page, the cluster is incomplete.
Example of a broken cluster:
— /en/page references /de/page and /en/page;
— /de/page references only /de/page;
— result: /de/page is missing a return link to /en/page, and search engines may ignore the hreflang annotation for both pages.
How to find missing return links:
— check each language page individually;
— list all hreflang references on each page;
— compare the lists and find asymmetries;
— use Google Search Console international targeting report to see errors.
For language attribute checks, you can use language attribute checker to verify that each page declares the correct lang attribute. This is not the same as hreflang, but a wrong lang attribute can compound hreflang problems.
Error 2: wrong language or region codes
Hreflang codes follow ISO 639-1 for language and ISO 3166-1 Alpha 2 for region. Common mistakes:
— using en-UK instead of en-GB;
— using uk for Ukrainian instead of ua for region United Kingdom;
— using pt-BR when the target is Portugal, not Brazil;
— using zh-CN when the target is Taiwan (zh-TW);
— mixing language-only and language-region codes inconsistently.
A wrong code can cause search engines to ignore the annotation or show the wrong version. After adding a new language, double-check every code against the official ISO lists. Do not guess.
Another subtle issue: if you use language-only codes for some pages and language-region codes for others, the cluster may become inconsistent. Decide on a pattern and apply it uniformly.
Error 3: missing or wrong x-default
x-default tells search engines which page to show when no other language or region matches the user. It is typically the global English version or a language selector page.
Common x-default mistakes:
— no x-default at all;
— x-default pointing to a page that does not exist;
— x-default pointing to a page that is not part of the cluster;
— multiple x-default values across the cluster.
When adding a new language, review x-default to make sure it still makes sense. If your global version is English, x-default should point to the English page. If you added a new global version, update x-default accordingly.
Error 4: hreflang in HTML vs sitemap conflicts
Hreflang can be implemented in three places: HTML link elements, HTTP headers, and XML sitemaps. If you use more than one method, the signals can conflict.
Common conflict scenarios:
— HTML references one set of pages, sitemap references another;
— HTTP header hreflang contradicts HTML hreflang;
— some pages use HTML, others use sitemap, without consistency.
The safest approach is to choose one method and apply it to all pages. XML sitemap hreflang is often easier to manage at scale, because it centralizes all references in one file. HTML hreflang is easier for small sites. Mixing the two without a clear reason usually leads to errors.
If you use a sitemap for hreflang, make sure every language version is included and every reference is reciprocal. A sitemap with missing return links is just as broken as HTML with missing return links.
Error 5: canonical conflicts with hreflang
Canonical and hreflang serve different purposes, but they can conflict if misconfigured. A canonical tag tells search engines which URL is the preferred version of a page. Hreflang tells search engines which language version to show.
Common conflict:
— the German page has a canonical pointing to the English page;
— result: search engines may treat the German page as a duplicate of the English page and ignore the hreflang annotation.
Correct setup:
— each language version should have a self-referencing canonical;
— canonical should point to the same language version, not to another language;
— hreflang should reference all language versions, including itself.
After adding a new language, check canonical tags on all existing pages. If any page points its canonical to the old language set, update it.
How to audit hreflang after adding a language
A practical audit sequence:
— list all language versions of the page;
— for each version, list all hreflang references;
— check that every reference has a return link;
— check that every code is valid ISO;
— check that x-default is present and correct;
— check that canonical is self-referencing;
— check that only one hreflang method is used;
— check Google Search Console for international targeting errors.
For a broader technical check after adding a language, SEO audit can help verify hreflang, canonical, lang attributes and redirects in one place. This is useful when you want to make sure the new language did not break anything else.
How to fix hreflang errors
Fix steps depend on the error:
— missing return links: add the missing references to every page in the cluster;
— wrong codes: correct the ISO codes and reapply consistently;
— missing x-default: add x-default pointing to the global version;
— HTML vs sitemap conflict: choose one method and remove the other;
— canonical conflict: make canonical self-referencing on every language version.
After fixing, request re-crawl of affected pages in Google Search Console and Yandex Webmaster. Hreflang changes can take days or weeks to be fully processed.
FAQ
Why did hreflang break after adding a new language?
Because every existing language page must reference the new page, and the new page must reference all existing pages. If any reference is missing, the cluster is incomplete and search engines may ignore it.
What is a return link in hreflang?
A return link is a reference from one language page back to another. If page A references page B, page B must also reference page A. Without return links, the cluster is broken.
Do I need x-default?
It is strongly recommended. x-default tells search engines which page to show when no language or region matches the user. Without it, search engines may choose a version you did not intend.
Can I use both HTML and sitemap hreflang?
You can, but it is risky. Conflicting signals can cause errors. The safest approach is to choose one method and apply it consistently.
What is the difference between hreflang and lang attribute?
The lang attribute declares the language of the page content. Hreflang tells search engines which language version to show. They serve different purposes and should both be correct.
How long does it take for hreflang changes to take effect?
It can take days or weeks. Search engines need to re-crawl the pages and process the annotations. Requesting re-crawl can speed up the process.
What happens if hreflang is wrong?
Search engines may show the wrong language version to users, ignore the annotation entirely, or treat language versions as duplicates. This can reduce traffic to the correct version.
Do I need hreflang if I only have one language?
No. Hreflang is only needed when you have multiple language or regional versions of the same content.
Can hreflang point to a page that redirects?
It is not recommended. Hreflang should point to the final URL, not to a redirect. Redirects in hreflang can cause errors.
How do I check hreflang errors?
Use Google Search Console international targeting report, and manually check each language page for return links, valid codes, x-default and canonical. A broader technical audit can also help verify the whole cluster.
