Hreflang Troubleshooting Guide: Finding and Fixing Errors

Hreflang is one of the most error-prone technical SEO implementations. Google's own John Mueller has called it "one of the most complex aspects of SEO," and the data backs that up: studies consistently find that 75% or more of sites using hreflang have implementation errors. [1]

The reasons are structural. Hreflang requires bidirectional confirmation between every page in a language set. A site with 10 language versions of 1,000 pages needs 10,000 pages to reference each other correctly, and a single missing or incorrect reference can break the annotation for the entire set. At that scale, errors are not just possible. They are inevitable without a systematic approach to validation and monitoring.

This guide covers every common hreflang error, how to diagnose each one, platform-specific gotchas, and a workflow for keeping your hreflang implementation healthy over time.

---

How hreflang errors affect your site

When hreflang annotations have errors, search engines ignore them. [1] Google does not partially process broken hreflang. If the annotation set for a page is invalid, Google falls back to its own algorithms for serving language and regional variants, which may not match your intent.

The consequences include:

• Wrong language version in search results. A user searching in French sees your English page instead of the French version.
• Duplicate content issues. Without valid hreflang signals, Google may treat your language variants as duplicate content and choose one version to index while suppressing others.
• Cannibalization. Multiple language versions compete for the same queries in the same market, splitting your ranking signals.
• Wasted crawl budget. Google still discovers and crawls all your language variants, but without hreflang it processes them less efficiently.

The worst part is that hreflang errors are silent. There is no warning in Google Search Console specifically for hreflang (the old International Targeting report has been deprecated). You discover problems through indirect signals: wrong pages ranking in specific markets, traffic anomalies in specific regions, or manual audits.

Missing return links

Missing return links are the single most common hreflang error and the one most likely to invalidate your entire annotation set.

What the error is

Hreflang is a bidirectional confirmation system. If page A says "my French version is page B," then page B must say "my English version is page A." If page B does not reference page A, the entire annotation is invalid and Google ignores it. [1]

Page A (English):
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />

Page B (French):
<!-- MISSING: <link rel="alternate" hreflang="en" href="https://example.com/page" /> -->

Why it happens

• A new language version was added but the existing pages were not updated to reference it
• A page was deleted or moved in one language, breaking the link from other versions
• Templates for different languages are maintained by different teams and get out of sync
• The CMS generates hreflang tags automatically but has a bug that skips certain pages or languages
• During a migration, hreflang annotations were updated for some languages but not all

How to diagnose

1. Crawl your site with a tool that checks hreflang bidirectionality (Screaming Frog, Sitebulb, or Ahrefs)
2. For each page, verify that every page it references also references it back
3. For sitemap-based hreflang, check that every URL in the hreflang sitemap has complete bidirectional references

How to fix

For detailed guidance on fixing missing return links, see hreflang missing return links. The key principles:

1. Generate hreflang annotations from a single source of truth (a mapping table of all URL variants) rather than maintaining them independently per language
2. When adding a new language, update all existing language versions simultaneously
3. When removing a page, remove its hreflang references from all other versions
4. Automate hreflang generation wherever possible to eliminate human error

Conflicting canonicals and hreflang

The interaction between canonical tags and hreflang is a common source of errors that invalidates hreflang without any obvious sign.

What the error is

If a page's canonical tag points to a different URL than the one used in hreflang annotations, Google ignores the hreflang for that page. [2]

Page: https://example.com/fr/produits
Canonical: <link rel="canonical" href="https://example.com/fr/products" />
Hreflang: <link rel="alternate" hreflang="fr" href="https://example.com/fr/produits" />

The hreflang references /fr/produits, but the canonical says the real URL is /fr/products. Google follows the canonical and ignores the hreflang annotation.

Common scenarios

• Trailing slash mismatch. The canonical uses https://example.com/page/ but hreflang references https://example.com/page (or vice versa).
• Protocol mismatch. The canonical uses https:// but hreflang references http://.
• www mismatch. The canonical uses www.example.com but hreflang references example.com.
• Parameter variants. The canonical strips query parameters but hreflang includes them.
• Cross-domain canonicalization. A page canonicalizes to a different domain, but hreflang references the original domain.

How to fix

Ensure that every URL in your hreflang annotations exactly matches the canonical URL for that page. Not approximately. Exactly. Including protocol, subdomain, path, trailing slash, and query string.

For a complete guide to this interaction, see hreflang and canonical.

Wrong language and region codes

Using incorrect language or region codes is surprisingly common, especially for languages with multiple regional variants.

What the error is

Hreflang uses ISO 639-1 language codes and optional ISO 3166-1 Alpha-2 region codes. [3] Using the wrong code means Google does not know which audience the page targets.

Common mistakes

• Using country codes as language codes. hreflang="uk" is not valid. Ukrainian is uk as a language code, but if you meant the United Kingdom, the correct tag is hreflang="en-GB". Similarly, hreflang="jp" is wrong; Japanese is ja.
• Inverted order. The language code comes first, then the region: en-US is correct. US-en is not.
• Wrong case. The convention is lowercase language, uppercase region: en-US. While Google is reportedly lenient about case, following the standard avoids ambiguity.
• Non-existent combinations. hreflang="en-EU" is not valid because EU is not a country code. There is no hreflang code for "European English."
• Three-letter codes. Hreflang uses ISO 639-1 two-letter codes, not ISO 639-2 three-letter codes. hreflang="fra" is wrong; use hreflang="fr".

For the complete code reference, see hreflang language codes. For language-specific guides, see the resources for French, German, Spanish, and Portuguese.

Missing x-default

The x-default hreflang value designates the default page that should be shown when no other language or region variant matches the user. [4]

What the error is

Not including an x-default annotation means Google has no fallback instruction. When a user's language does not match any of your hreflang annotations, Google chooses which version to show based on its own signals, which may not be your preferred default.

When x-default matters most

• You have a language-selection page or homepage that detects the user's language
• You want a specific language version (usually English) to serve as the global default
• Your site covers some but not all languages, and you want a clear fallback for uncovered regions

How to fix

Add x-default to every page that has hreflang annotations:

<link rel="alternate" hreflang="en" href="https://example.com/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />

The x-default URL can be:

• Your main language version (most common)
• A language-selection landing page
• A page that auto-detects and redirects (though be careful with hreflang and redirects)

For full guidance, see hreflang x-default.

Missing self-referencing hreflang

Every page must include a hreflang annotation that points to itself. This is the self-referencing tag. [1]

What the error is

<!-- On the English page at https://example.com/page -->
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="de" href="https://example.com/de/page" />
<!-- MISSING: <link rel="alternate" hreflang="en" href="https://example.com/page" /> -->

Without the self-referencing tag, the annotation set is incomplete. Google may still process it, but the lack of self-reference reduces the signal's reliability.

How to fix

Include the current page in its own hreflang annotation set. Every page should reference itself along with all its language variants.

For details, see self-referencing hreflang.

Diagnosis tools and methods

Crawl-based diagnosis

The most comprehensive approach is crawling your entire site and checking every hreflang annotation:

1. Screaming Frog. The Hreflang tab shows all annotations and flags errors including missing return links, non-200 targets, and mismatched canonicals.
2. Sitebulb. Provides visual hreflang cluster analysis showing which pages are connected and where links are missing.
3. Ahrefs Site Audit. Checks hreflang annotations as part of its site audit and flags common errors.

For a comparison, see hreflang checker tools compared.

Manual spot-checking

For quick checks on individual pages:

1. View the page source and search for hreflang
2. Verify each hreflang URL is accessible (returns 200)
3. Visit each referenced URL and verify it contains a return link to the original page
4. Check that language codes are valid
5. Verify canonical tags match hreflang URLs

Google Search Console

While Search Console no longer has a dedicated hreflang report, you can still find hreflang-related issues:

• Pages report. Look for alternate pages being flagged as duplicates or being excluded from indexing.
• URL Inspection tool. Check individual pages to see which alternate versions Google has discovered.
• Performance report. Filter by country to see whether the right language versions are appearing in each market.

Sitemap inspection

If you implement hreflang via sitemap (rather than HTML tags), inspect the sitemap directly:

<url>
  <loc>https://example.com/page</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/page" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
</url>

Verify that the sitemap contains hreflang entries for every page in every language, and that all bidirectional references are present. See hreflang in XML sitemap for the format specification.

Platform-specific issues

WordPress

WordPress hreflang is typically managed through plugins (WPML, Polylang, TranslatePress, or Yoast SEO). Each plugin has its own quirks:

WPML:

• Automatically generates hreflang tags for translated pages
• Can break if post translations become disconnected (deleted translation, changed slug)
• Verify that the "Language URL Format" setting matches your canonical URLs
• Check for conflicts with caching plugins that serve stale hreflang tags

Polylang:

• Generates hreflang based on language taxonomy relationships
• Missing translations do not generate hreflang tags (which is correct behavior), but pages with partial translations generate incomplete sets
• Verify the language switcher URLs match the hreflang URLs

Yoast SEO:

• Does not manage translations itself; integrates with WPML or Polylang
• Can conflict with other plugins that also output hreflang tags, resulting in duplicate annotations

See hreflang in WordPress for platform-specific configuration.

Shopify

Shopify's hreflang implementation has specific limitations:

• Shopify generates hreflang automatically for stores using Shopify Markets
• Third-party translation apps may generate their own hreflang tags, potentially conflicting with Shopify's built-in tags
• Product URLs with variant parameters can cause hreflang mismatches
• Ensure that your theme does not output duplicate hreflang tags alongside Shopify's automatic ones

See hreflang on Shopify for workarounds.

Headless CMS and frameworks

Sites using Next.js, Nuxt.js, or other frameworks need to implement hreflang programmatically:

• Ensure server-rendered pages include hreflang in the initial HTML (not just after JavaScript execution)
• Client-side routing can cause hreflang tags to become stale if not updated on navigation
• Verify that pre-rendered or statically generated pages have correct hreflang for each language version

See hreflang in Next.js for implementation patterns.

Webflow and Squarespace

These platforms have limited native hreflang support:

• Webflow does not generate hreflang automatically; you must add it through custom code
• Squarespace has limited international SEO features
• Both platforms may require using the sitemap-based hreflang approach rather than HTML tags

See hreflang for Webflow and Squarespace for implementation guidance.

Validation workflow

A repeatable validation workflow prevents hreflang errors from accumulating.

Initial implementation validation

When first implementing hreflang (or after major changes):

1. Generate the complete URL mapping. Create a spreadsheet with every page and its language variants. This is your source of truth.
2. Implement hreflang from the mapping. Whether using HTML tags, HTTP headers, or sitemaps, generate the annotations from this single source.
3. Crawl and validate. Run a full-site crawl to check every annotation. Fix all errors before launch.
4. Test in Search Console. Use URL Inspection to verify Google sees the correct hreflang for a sample of pages.
5. Baseline your metrics. Record current organic traffic by country/language as a baseline for measuring the impact.

Post-change validation

After any content, structural, or platform change:

1. Identify affected pages. Which pages were added, removed, or had their URLs changed?
2. Update the URL mapping. Add new pages, remove deleted ones, update changed URLs.
3. Regenerate hreflang. Update annotations for all affected pages and their language variants (not just the changed language).
4. Spot-check bidirectionality. For changed pages, manually verify return links from each language variant.
5. Monitor for 2 weeks. Watch Search Console for indexing changes in affected pages.

Ongoing validation

On a regular cadence (monthly for large sites, quarterly for smaller ones):

1. Full-site crawl with hreflang checking. Catch drift from content changes, CMS updates, and template modifications.
2. Cross-reference with Search Console. Compare indexed pages against your hreflang mapping. Are all language variants being indexed?
3. Check for redirect issues. URLs in hreflang annotations should not redirect. If any do, update the annotations to use the final destination URL.
4. Review analytics by market. Are users in each target market seeing the correct language version? Unexpected patterns may indicate hreflang failures.

Monitoring hreflang health

Key metrics to track

• Bidirectional completeness. The percentage of hreflang annotations that have valid return links. Target: 100%.
• URL validity. The percentage of hreflang target URLs that return 200. Target: 100%.
• Canonical consistency. The percentage of hreflang URLs that match their page's canonical tag. Target: 100%.
• Coverage completeness. The percentage of pages that have hreflang annotations for all available language versions. Gaps indicate missing translations or missing annotations.
• Search Console indexing. The number of alternate pages indexed in each language version.

Alerting

Set up alerts for:

• Large drops in hreflang annotation count (could indicate a template change that broke hreflang output)
• New 404 or redirect URLs appearing in hreflang annotations
• Pages losing their alternate versions in Search Console

Integration with other monitoring

Hreflang health depends on several other aspects of your site:

• Sitemap monitoring. If hreflang is implemented via sitemap, sitemap errors directly affect hreflang.
• Redirect monitoring. Redirect changes can break hreflang annotations overnight.
• Content monitoring. New pages need hreflang. Deleted pages need hreflang cleanup.

Common error reference table

| Error | Impact | Diagnosis | Fix | |-------|--------|-----------|-----| | Missing return link | Annotation ignored | Crawl bidirectionality check | Update all language versions | | Canonical mismatch | Annotation ignored | Compare canonical to hreflang URL | Match URLs exactly | | Wrong language code | Wrong audience targeted | Code validation check | Use ISO 639-1 codes | | Missing x-default | No fallback for unmatched users | Check annotation set | Add x-default to all pages | | Missing self-reference | Weakened signal | Check annotation set | Include self-referencing tag | | Redirect in hreflang | Delayed/incorrect processing | HTTP status check on all URLs | Use final destination URLs | | Noindex on target | Annotation ignored | Check meta robots on targets | Remove noindex or remove from hreflang | | Duplicate annotations | Confusing signals | View source, check for duplicates | Remove duplicate output source | | Sitemap hreflang incomplete | Partial annotation set | Compare sitemap to page-level tags | Ensure all variants in sitemap |

---

References

1. Google Search Central, "Tell Google about localized versions of your page," Google Developers, 2024. https://developers.google.com/search/docs/specialty/international/localized-versions

2. Google Search Central, "Consolidate duplicate URLs," Google Developers, 2024. https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls

3. ISO 639-1:2002, "Codes for the representation of names of languages, Part 1: Alpha-2 code," International Organization for Standardization. https://www.iso.org/standard/22109.html

4. Google Search Central, "x-default hreflang value," Google Developers. https://developers.google.com/search/docs/specialty/international/localized-versions#xdefault

5. ISO 3166-1:2020, "Codes for the representation of names of countries and their subdivisions, Part 1: Country codes," International Organization for Standardization. https://www.iso.org/standard/72219.html

6. John Mueller, Google Search Advocate, comments on hreflang complexity, Google Search Central YouTube channel and various Google Webmaster Hangouts. https://www.youtube.com/googleSearchCentral

7. RFC 5646, "Tags for Identifying Languages," IETF, September 2009. https://www.rfc-editor.org/rfc/rfc5646