Learn
Hreflang Debugging Guide: Fix Multilingual SEO, Return Tags, and x-default
A practical hreflang debugging guide: the rules every cluster must follow, the common return-tag and language-code errors, and how to validate multilingual SEO.
Run a fresh DomainLens audit and use the report as your priority list.
What hreflang does and why clusters break
Hreflang tells Google which language or regional version of a page to show each user. If you have the same content in English, German, and Spanish, hreflang links those URLs as a cluster so a Spanish searcher gets the Spanish page instead of the English one — without any of them being treated as duplicate content.
It breaks because hreflang is not a hint you set once per page; it is a set of mutual declarations. Every URL in the cluster must point at every other URL, including itself, and every one of those must point back. Miss a single return link, use one wrong language code, or point at a redirecting URL, and Google ignores the annotation for that pair.
The rules every hreflang cluster must follow
- Bidirectional (return tags): if page A links to B with hreflang, B must link back to A, or both are ignored.
- Self-referencing: each page must include an hreflang entry pointing to itself.
- Valid codes: language in ISO 639-1 (e.g. en, de), optional region in ISO 3166-1 alpha-2 (e.g. en-GB) — region alone is invalid.
- Absolute, indexable URLs: every hreflang target must be a canonical, 200-status, non-redirecting, non-noindex URL.
- Canonical agreement: the canonical of each localized page must be self-referential, not pointing to another language.
- One x-default for the fallback (language/region selector or default version) is recommended, not required.
The most common hreflang errors
- "No return tags" — the most frequent Search Console error: A points to B, but B does not point back.
- Wrong codes: using en-UK instead of en-GB, or a language code that does not exist, so the entry is dropped.
- Pointing hreflang at a URL that redirects or is noindexed, which invalidates that target.
- hreflang conflicting with canonical — a localized page whose canonical points to the English version cancels its own hreflang.
- Mixing implementations (HTML head, HTTP header, and sitemap) inconsistently, so the sets disagree.
How to debug a hreflang cluster
- Pick one URL and list every hreflang entry it declares, then open each target and confirm it declares the return link and a self-reference.
- Check Search Console’s International Targeting / hreflang report (or a crawler’s hreflang audit) for "no return tags" and unknown language codes at scale.
- Confirm every target returns 200, is not redirected, and is not noindexed.
- Verify each localized page’s canonical is self-referential, not pointing across languages.
- Pick one implementation method (usually HTML head or sitemap) and make it the single source of truth.
Mistakes that quietly break international SEO
- Assuming hreflang boosts rankings — it only controls which existing version is shown, it does not lift the cluster.
- Using country codes as language codes (e.g. "uk" for Ukrainian, which actually means United Kingdom region).
- Auto-redirecting users by IP so Googlebot only ever sees one version and cannot validate the others.
- Adding hreflang to only some templates and forgetting paginated, filtered, or parameterised variants.
How to validate hreflang
After the fix, re-crawl the cluster and confirm every pair is bidirectional with valid codes and indexable targets, then watch the hreflang report in Search Console clear its "no return tag" errors over the following days. The real-world test is a localized search returning the correct language version.
This maps directly to how DomainLens handles locales: every localized URL is emitted with matching, self-consistent alternates, and the canonical of each language points to itself — the same discipline that keeps a multilingual cluster valid rather than silently ignored.