How to Fix Hreflang Tag Errors (Complete Implementation Guide for Multi-Language Sites)
Moderate 31 min 2026-03-20

How to Fix Hreflang Tag Errors (Complete Implementation Guide for Multi-Language Sites)

Quick Summary

  • What this covers: Hreflang tag errors confuse search engines and send users to wrong language versions. Learn how to audit, fix, and validate hreflang implementation for international SEO success.
  • Who it's for: site owners and SEO practitioners
  • Key takeaway: Read the first section for the core framework, then use the specific tactics that match your situation.

Hreflang tags tell search engines which language and regional version of a page to serve users. When implemented incorrectly, users land on Spanish content when they need English, or UK visitors see US pricing and shipping information. Search engines also suffer—they can't determine which version ranks for which query.

This guide covers hreflang error diagnosis, correction protocols, and validation workflows. You'll learn proper tag syntax, common implementation mistakes, and testing methodologies that prevent international SEO disasters.

Understanding Hreflang Tag Purpose and Structure

The hreflang attribute lives in HTML link elements or XML sitemaps. It creates reciprocal relationships between language and regional variants of identical content.

A basic hreflang implementation looks like this:

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

Each page containing this markup tells Google: "This page exists in English, Spanish, and German versions. The English version serves as the default for unmatched languages."

Language codes follow ISO 639-1 standards (two-letter codes like "en," "es," "de"). Region codes follow ISO 3166-1 Alpha-2 standards (two-letter codes like "US," "GB," "CA"). Combined codes specify both language and region: "en-US" for US English, "en-GB" for British English, "es-MX" for Mexican Spanish.

The x-default value designates the fallback version for users whose language preferences don't match any specified hreflang tags. This typically points to your primary market version or a language selector page.

Hreflang tags must be reciprocal. If your English page references the Spanish version, the Spanish version must reference the English page back. Missing reciprocity is the most common hreflang error.

Common Hreflang Errors and Their Symptoms

Seven error patterns account for most hreflang failures.

Missing return tags occur when Page A references Page B, but Page B doesn't reference Page A back. If example.com/en references example.com/es, but the Spanish page's hreflang tags don't include the English page, Google ignores both tags. This breaks the entire language relationship chain.

Symptoms include users reaching the wrong language version despite browser language settings, and Google Search Console showing "No return tags" errors in the International Targeting report.

Incorrect language codes use wrong ISO values. Common mistakes include "en-uk" instead of "en-GB," "cn" instead of "zh-CN," or full language names like "english" instead of "en."

Symptoms include Google Search Console reporting "Invalid language code" errors, and language versions ranking in incorrect geographic regions.

Conflicting hreflang signals happen when HTML head tags, HTTP headers, and XML sitemaps provide different hreflang values for the same page. If your HTML says hreflang="en-US" but your sitemap says hreflang="en-GB," Google chooses arbitrarily or ignores both.

Symptoms include inconsistent language serving and International Targeting reports showing "Conflicting hreflang signals."

Self-referential errors occur when pages include hreflang tags but don't reference themselves. Every page with hreflang tags must include a self-referential tag:

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

Missing self-references break the reciprocal relationship requirement.

Absolute vs. relative URL inconsistencies create errors when some hreflang URLs use absolute paths (https://example.com/page) while others use relative paths (/page). Hreflang tags require fully qualified absolute URLs including protocol and domain.

Canonical tag conflicts arise when a page's canonical URL doesn't match its self-referential hreflang URL. If your English page has <link rel="canonical" href="https://example.com/page" /> but the self-referential hreflang points to https://example.com/en/page, Google receives conflicting signals about the page's authoritative URL.

Character encoding issues corrupt non-Latin characters in hreflang URLs. Arabic, Chinese, Japanese, and Cyrillic characters must be properly encoded. URLs like example.com/продукт should encode to example.com/%D0%BF%D1%80%D0%BE%D0%B4%D1%83%D0%BA%D1%82 in hreflang tags.

Auditing Your Hreflang Implementation

Start with Google Search Console's International Targeting report. Navigate to Settings → International Targeting → Language. This report surfaces three critical metrics:

Export the full error list. Each error includes the source URL, target URL, and specific issue description.

Screaming Frog SEO Spider provides deeper analysis. Configure a crawl with hreflang validation enabled:

  1. Launch Screaming Frog and crawl your site
  2. Navigate to Configuration → Spider → Advanced → Rendering
  3. Enable JavaScript rendering if your site loads hreflang tags via JavaScript
  4. After crawling, go to Bulk Export → Hreflang
  5. Export all hreflang annotations

This export reveals:

Manual spot checks catch errors automated tools miss. Visit five random international pages. View source and verify:

Compare hreflang tags in three locations:

  1. HTML <head> section (view page source)
  2. HTTP headers (use browser dev tools Network tab, check Response Headers)
  3. XML sitemap (download and inspect your international sitemap)

If values differ across these sources, you have conflicting signals. For related technical SEO auditing, see our guide on fixing indexing issues.

Fixing Missing Return Tags

Missing return tags represent the most common hreflang error. Google requires bidirectional references—if Page A references Page B, Page B must reference Page A.

Identify missing return tags using Screaming Frog's Bulk Export → Hreflang report. Sort by "Missing Return Tags" column. Each row shows a source page referencing a target page that doesn't reference back.

Correction methodology:

  1. Open the target page's template or HTML file
  2. Locate existing hreflang tags in the <head> section
  3. Add the missing reciprocal reference

Example: If example.com/en references example.com/es, but the Spanish page lacks the return tag, add this to example.com/es:

<link rel="alternate" hreflang="es" href="https://example.com/es" />
<link rel="alternate" hreflang="en" href="https://example.com/en" />

For template-driven sites (WordPress, Shopify, Magento), implement hreflang through plugins or theme functions:

WordPress: Use the WPML plugin or Polylang plugin, both of which auto-generate reciprocal hreflang tags. Configure language relationships in plugin settings.

Shopify: Install the Weglot or Langify apps. These apps automatically manage hreflang tags across all language versions.

Custom implementations: If you're hardcoding hreflang tags, create a function that programmatically generates complete tag sets for every language version.

<?php
function generate_hreflang_tags($page_slug, $languages) {
    foreach ($languages as $lang => $url) {
        echo '<link rel="alternate" hreflang="' . $lang . '" href="' . $url . $page_slug . '" />';
    }
    echo '<link rel="alternate" hreflang="x-default" href="https://example.com/' . $page_slug . '" />';
}

$languages = [
    'en' => 'https://example.com/',
    'es' => 'https://example.com/es/',
    'de' => 'https://example.com/de/'
];

generate_hreflang_tags('product-page', $languages);
?>

This approach ensures every page automatically generates complete reciprocal tag sets.

After implementing corrections, use the Hreflang Tags Testing Tool (https://technicalseo.com/tools/hreflang/) to validate tag reciprocity. Enter any language version URL and verify all referenced pages return proper tags.

Correcting Language and Region Code Errors

Invalid language codes prevent Google from understanding which language variants exist. Common mistakes include:

Correction protocol:

  1. List all language codes currently in use across your site
  2. Cross-reference against ISO 639-1 language codes
  3. Cross-reference region codes against ISO 3166-1 Alpha-2 codes
  4. Create a mapping table for replacements

Example mapping:

Current (Wrong) Corrected
en-uk en-GB
cn zh-CN
pt pt-BR (if Brazilian Portuguese)
es-sp es-ES
en-en en

Find-and-replace strategy works for template-based implementations:

  1. Search codebase for all instances of incorrect codes
  2. Replace with correct codes using global find-and-replace
  3. Test on staging environment before deploying to production

For database-driven implementations, run SQL updates:

UPDATE pages
SET hreflang_code = 'en-GB'
WHERE hreflang_code = 'en-uk';

UPDATE pages
SET hreflang_code = 'zh-CN'
WHERE hreflang_code = 'cn';

Language-only vs. language-region combinations: Use language-only codes (en, es, de) when content serves all speakers of that language regardless of region. Use language-region combinations (en-US, en-GB, es-MX, es-ES) when content differs by region—prices, spelling, local terminology.

After corrections, validate with Google Search Console. International Targeting reports update within 1-2 weeks of tag corrections.

Resolving Conflicting Hreflang Signals

Conflicting signals occur when hreflang values differ across implementation methods—HTML tags, HTTP headers, and XML sitemaps.

Choose one implementation method as your primary source of truth:

HTML head tags work best for small-to-medium sites with clear template structures. They're easy to debug (view source to see tags) and don't require separate sitemap management.

HTTP headers suit API-driven sites or non-HTML content (PDFs, images). Implement via server configuration:

# Apache .htaccess example
<FilesMatch "\.(pdf|jpg|png)$">
    Header set Link: '<https://example.com/document.pdf>; rel="alternate"; hreflang="en"'
    Header set Link: '<https://example.com/es/document.pdf>; rel="alternate"; hreflang="es"'
</FilesMatch>

XML sitemaps handle large-scale implementations efficiently (1000+ pages). Create a separate international sitemap or add hreflang annotations to existing sitemaps:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/page</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
</urlset>

Audit for conflicts:

  1. Check HTML head tags (view page source)
  2. Check HTTP headers (browser dev tools → Network → select page load → Response Headers)
  3. Check XML sitemap entries

If values differ, decide which implementation method to keep and remove others. Never maintain hreflang annotations in multiple locations unless values are identical.

For complex migrations or site structure changes, refer to our guide on fixing redirect loops to understand how URL changes affect hreflang relationships.

Fixing Self-Referential Tag Issues

Every page with hreflang tags must reference itself. This self-referential tag confirms the page's own language/region designation.

Detect missing self-references using Screaming Frog:

  1. Crawl site with hreflang validation enabled
  2. Navigate to Bulk Export → Hreflang
  3. Filter for pages with hreflang tags
  4. Check if each page's URL appears in its own hreflang tag set

Add self-referential tags to every international page. If your English page at example.com/en lacks a self-reference, add:

<link rel="alternate" hreflang="en" href="https://example.com/en" />

The complete tag set for a page should always include:

Example complete implementation:

<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/page" />
<link rel="alternate" hreflang="es-MX" href="https://example.com/mx/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />

Notice the first tag references the page itself (self-referential).

Implementing x-default Properly

The x-default hreflang value handles users whose language settings don't match any specified variants. Common implementation mistakes reduce its effectiveness.

X-default should point to:

Don't point x-default to:

Example x-default configurations:

For a US-primary business:

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

For a business with equal international markets using a language selector:

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

Every page with hreflang tags must include an x-default tag. Missing x-default tags create ambiguity for users outside your specified regions.

Fixing Canonical Tag Conflicts

Canonical tags specify the preferred version of duplicate or similar content. When canonical tags conflict with hreflang self-references, Google can't determine which URL to prioritize.

Conflict example:

<!-- On https://example.com/us/page -->
<link rel="canonical" href="https://example.com/page" />
<link rel="alternate" hreflang="en-US" href="https://example.com/us/page" />

This page says "my canonical version is example.com/page" but "my hreflang self-reference is example.com/us/page." Contradictory.

Resolution principle: Each language/region version should be its own canonical. The canonical URL and hreflang self-reference must match.

Corrected implementation:

<!-- On https://example.com/us/page -->
<link rel="canonical" href="https://example.com/us/page" />
<link rel="alternate" hreflang="en-US" href="https://example.com/us/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/us/page" />

Audit for conflicts:

  1. Crawl site with Screaming Frog
  2. Export Bulk Export → All Inlinks
  3. Filter for pages with both canonical tags and hreflang tags
  4. Compare canonical URL to hreflang self-reference URL
  5. Flag mismatches

For each mismatch, decide: Should this page be its own canonical (independent regional version), or should it canonicalize to another version (duplicate content)?

If pages are independent regional versions with unique content, make each its own canonical. If they're duplicate translations of identical content, you still make each its own canonical—hreflang tells Google they're related variations.

For understanding how canonical tags interact with site architecture, see our guide on fixing multiple H1 tags, which covers content hierarchy signals.

Validating Hreflang Implementation

After corrections, validation confirms proper implementation before Google crawls and processes changes.

Google Search Console validation:

  1. Navigate to Settings → International Targeting → Language
  2. Check for new errors (wait 7-10 days after implementation)
  3. Monitor "Valid" count—should increase as errors resolve

Hreflang Tags Testing Tool (https://technicalseo.com/tools/hreflang/):

  1. Enter any page URL with hreflang tags
  2. Tool fetches the page and all referenced hreflang URLs
  3. Validates reciprocity, language code format, and self-references
  4. Reports errors with specific correction guidance

Merkle's Hreflang Tag Checker (https://technicalseo.com/tools/hreflang/) provides bulk validation:

  1. Upload a list of URLs to test
  2. Tool crawls each URL and extracts hreflang tags
  3. Generates report showing all errors across the URL set

Manual verification checklist:

For five random pages across different language versions:

Browser language testing confirms correct serving:

  1. Change browser language settings (Chrome: Settings → Languages → Move preferred language to top)
  2. Clear cookies and cache
  3. Search for your target keyword in Google
  4. Verify correct language version appears in results
  5. Click through and confirm Google serves the matching language page

Geographic testing validates region-specific serving. Use VPN services to simulate access from different countries:

  1. Connect VPN to target country (UK for en-GB testing, Mexico for es-MX)
  2. Search Google in private browsing mode
  3. Verify appropriate regional version ranks and serves

Repeat testing from 3-5 different geographic locations across your target markets.

Handling Dynamic Hreflang Implementation

Sites using JavaScript frameworks (React, Vue, Angular) often load hreflang tags dynamically. This creates validation challenges—hreflang tags don't appear in initial HTML, making them invisible to some crawlers.

Server-side rendering (SSR) solves this. Configure your framework to render hreflang tags on the server before sending HTML to browsers:

Next.js example:

// pages/_app.js
import Head from 'next/head';

function MyApp({ Component, pageProps, router }) {
  const languages = {
    'en': 'https://example.com',
    'es': 'https://example.com/es',
    'de': 'https://example.com/de'
  };

  return (
    <>
      <Head>
        {Object.entries(languages).map(([lang, baseUrl]) => (
          <link
            key={lang}
            rel="alternate"
            hreflang={lang}
            href={`${baseUrl}${router.asPath}`}
          />
        ))}
        <link
          rel="alternate"
          hreflang="x-default"
          href={`https://example.com${router.asPath}`}
        />
      </Head>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

This generates hreflang tags server-side for every route, ensuring crawlers see them immediately.

Alternative: HTTP header implementation bypasses HTML entirely:

// Next.js API route or middleware
export function middleware(req) {
  const languages = ['en', 'es', 'de'];
  const links = languages.map(lang =>
    `<https://example.com/${lang === 'en' ? '' : lang + '/'}${req.url}>; rel="alternate"; hreflang="${lang}"`
  );
  links.push(`<https://example.com${req.url}>; rel="alternate"; hreflang="x-default"`);

  return new Response(null, {
    headers: {
      'Link': links.join(', ')
    }
  });
}

Validate JavaScript-rendered hreflang:

  1. Use Google's Rich Results Test (https://search.google.com/test/rich-results)
  2. Enter your page URL
  3. Check "View tested page" → "More Info" → "HTML"
  4. Verify hreflang tags appear in rendered HTML

If tags don't appear, Google isn't executing your JavaScript. Implement SSR or switch to HTTP header method.

For other JavaScript SEO challenges, see our guide on fixing JavaScript SEO crawling issues.

Hreflang for Multi-Regional Content

Language vs. region targeting requires different approaches. Language-only targeting (en, es, de) serves all speakers of that language. Language-region targeting (en-US, en-GB, en-AU) serves specific geographic markets within a language.

When to use language-only codes:

When to use language-region codes:

Example: Global English content with regional variations:

<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/page" />
<link rel="alternate" hreflang="en-CA" href="https://example.com/ca/page" />
<link rel="alternate" hreflang="en-AU" href="https://example.com/au/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />

Each regional variant has region-specific pricing, contact information, and legal disclaimers, justifying separate hreflang values.

Mixing language and language-region codes:

You can combine both approaches. If you have Spanish content serving all Spanish speakers plus Mexican-specific content:

<link rel="alternate" hreflang="es" href="https://example.com/es/page" />
<link rel="alternate" hreflang="es-MX" href="https://example.com/mx/page" />

Google serves es-MX to users in Mexico and es to all other Spanish speakers.

Monitoring Hreflang Performance

After implementation, monitor performance metrics to verify hreflang tags improve user experience and rankings.

Google Search Console performance report shows language-specific query and click data:

  1. Navigate to Performance
  2. Click "+ New" → "Query" → filter for language-specific terms
  3. Compare impressions and clicks across language versions

Properly implemented hreflang should show:

Google Analytics 4 geographic and language reports reveal user behavior:

  1. Navigate to Reports → User → Demographics → Country
  2. Check bounce rate and session duration by country
  3. Navigate to User → Tech → Language
  4. Compare engagement metrics across language settings

Improvements suggest correct language serving. High bounce rates in specific countries indicate potential hreflang errors—users may still reach wrong language versions.

Ranking tracking by country uses tools like SEMrush or Ahrefs:

  1. Set up location-specific rank tracking for target keywords
  2. Monitor rankings in each target country
  3. Verify appropriate language version ranks in each market

If your French version ranks in Germany or your UK version ranks in Australia, hreflang implementation may need refinement.

Traffic source analysis identifies organic search traffic from international markets:

  1. In GA4, navigate to Traffic Acquisition
  2. Filter for Organic Search traffic
  3. Apply secondary dimension: Country
  4. Check landing pages for each country

Each country should primarily land on its designated language/region version. If UK traffic lands on US pages, review hreflang configuration for en-GB to en-US relationships.

FAQ

Do I need hreflang tags if I only have one language?

No. Hreflang tags only serve sites with multiple language or regional versions of content. Single-language sites don't need them. However, if you serve the same language to different countries with regional differences (en-US vs. en-GB), hreflang helps Google serve the right regional version.

Can I use hreflang for completely different content in different languages?

No. Hreflang indicates equivalent content in different languages or regions. If your Spanish page discusses entirely different topics than your English page, don't connect them with hreflang. Only link pages that are translations or regional adaptations of each other.

Should I use hreflang for different countries speaking the same language?

Only if content differs by country. If your UK and US English pages have identical content, you don't need separate hreflang tags—use a single "en" tag. If prices, products, or terminology differ, implement en-GB and en-US separately.

What's the difference between hreflang and canonical tags?

Canonical tags consolidate duplicate content to a single preferred URL. Hreflang tags indicate equivalent content in different languages without consolidation—each language version can rank independently. Never canonicalize different language versions to each other.

Can I implement hreflang in both HTML and XML sitemaps?

Yes, but values must be identical. Google accepts hreflang from HTML head tags, HTTP headers, or XML sitemaps. If you implement in multiple locations with conflicting values, Google may ignore all of them. Choose one method for consistency.

How long does it take for Google to process hreflang changes?

Google typically reprocesses pages within 1-2 weeks of crawling updated hreflang tags. Large sites with many pages may take longer. Google Search Console's International Targeting report updates as Google processes changes.

Do I need hreflang for pages in site navigation menus vs. content pages?

Yes. Every page with language variants needs hreflang tags—homepage, category pages, product pages, blog posts, etc. Inconsistent implementation (only tagging some pages) confuses Google and reduces effectiveness.

What happens if I point hreflang to a 404 page?

Google ignores the entire hreflang tag set for that page. Regularly audit hreflang URLs to ensure all referenced pages return 200 status codes. Use Screaming Frog to check status codes of all hreflang targets.

Can I use hreflang for translated subdomains (es.example.com)?

Yes. Hreflang works across subdomains, subdirectories, and completely separate domains. The implementation is identical—use absolute URLs including the subdomain in all hreflang tags.

Should I include hreflang tags on pages that aren't translated yet?

No. Only implement hreflang when translated or regional versions exist. Don't create hreflang tags pointing to future pages that aren't live. Add tags as you publish each new language version.

When This Fix Isn't Your Priority

Skip this for now if:

Frequently Asked Questions

How long does this fix take to implement?

Most fixes in this article can be implemented in under an hour. Some require a staging environment for testing before deploying to production. The article flags which changes are safe to deploy immediately versus which need QA review first.

Will this fix work on WordPress, Shopify, and custom sites?

The underlying SEO principles are platform-agnostic. Implementation details differ — WordPress uses plugins and theme files, Shopify uses Liquid templates, custom sites use direct code changes. The article focuses on the what and why; platform-specific how-to links are provided where available.

How do I verify the fix actually worked?

Each fix includes a verification step. For most technical SEO changes: check Google Search Console coverage report 48-72 hours after deployment, validate with a live URL inspection, and monitor the affected pages in your crawl tool. Ranking impact typically surfaces within 1-4 weeks depending on crawl frequency.

This is one piece of the system.

Built by Victor Romo (@b2bvic) — I build AI memory systems for businesses.

See The Full System View Repo
← All Fixes