Multilingual Site hreflang Errors | 7 Technical Reasons Why Tags Stop Working
For example, language code format errors, incomplete link paths, and other details may prevent search engines from correctly identifying the language or region of a page, and may even cause multilingual pages to compete for traffic, missing the target audience.
This article, from a technical practical perspective, summarizes the 7 most common hreflang configuration errors, and recommends regular verification using tools to avoid small errors affecting overall optimization results.
Server Configuration:
Dynamic Rendering Page Repair (such as React):
In server-side rendering (SSR) logic, dynamically generate self-referencing tags based on the current page language:
Solution 3: Google Search Console Parameter Handling
Language or Region Code Format Errors
For example, using uppercase letters (such asEN-US) or spelling errors (such as writing zh-CN as zh-CH) will cause search engines to fail to correctly parse the target region for the page, or even misinterpret it as an invalid tag.
Even if the code appears correct (such as using es-ES instead of es), redundant information may interfere with the matching logic.
The impact is significant - for example, Spanish users' search traffic may be incorrectly assigned to Portuguese pages.
ISO Standard Code Rules
The hreflang code consists of two parts: "language" and "region", and must strictly follow ISO standards:- Language Code: Must use lowercase letters per ISO 639-1 standard (such as
en,es,zh), only 2-letter abbreviations are supported. - Region Code: Optional, uses uppercase letters per ISO 3166-1 standard (such as
US,GB,CN), only country/region abbreviations are used. - Combined Format: Language and region are separated by a hyphen, for example
en-US(American English),zh-CN(Simplified Chinese).
- When only a language code exists (such as
fr), it indicates targeting all French users without regional restrictions. - Traditional Chinese should use
zh-Hant(Traditional Chinese) orzh-Hant-TW(Traditional Chinese for Taiwan), notzh-TW(which may be misinterpreted as Simplified Chinese for Taiwan).
Typical Error Scenarios and Consequences
Error 1: Case Confusion- Error Example:
EN-us(uppercase language code + lowercase region),Zh-cn(first letter of language capitalized). - Consequence: Search engines may completely ignore the tag, causing the page to fail to match target users.
- Error Example:
pt-BZ(the correct code for Brazil isBR),eu(Basque written aseu, but some engines may not support minority languages). - Consequence: Minority languages or incorrect region codes will cause pages to fail proper indexing, and traffic will flow to the default language page.
- Error Example:
es-ES(Spanish + Spain region, actually onlyesis needed),en-US-UK(invalid multi-region combination). - Consequence: Redundant information confuses engines, which will preferentially adopt simpler competing pages.
Recommended Tools and Verification Methods
- Google hreflang Testing Tool: Directly enter the URL to check if the code is parsed (requires Search Console usage).
- Screaming Frog: When crawling the site, filter hreflang tags and batch export error codes (paid version supported).
- Hreflang Validator (third-party tool): Free online detection, marking format errors and conflicting links.
Practical Correction Steps
Using a WordPress site as an example: Check Existing Code: Use plugins (such as Yoast SEO) or directly view the page source code to find<link rel="alternate" hreflang="..." /> tags.
Batch Replace Error Codes:
- If using a multilingual plugin (such as WPML), directly modify the "language code" format in the language settings.
- When manually modifying, ensure all pages use a unified format (such as globally replacing
ENwithen).
- Only add when regional subdivision is needed (such as
en-GBfor UK users), otherwise keep the pure language code (such asfr).
Not Using Complete Absolute URLs
Many webmasters mistakenly think that relative paths (such as/de/page) or omitting the protocol (such as example.com/de) can simplify configuration, but this actually causes serious problems.
For example, if a page has both http and https versions, not writing the full protocol may cause engines to mistakenly treat them as two independent pages, diluting authority;
Additionally, for sites using subdomains or subdirectory structures that fail to unify the use of complete URLs, marking may fail due to path ambiguity (such as mixed use of mobile and desktop URLs).
Definition and Necessity of Absolute URLs
Absolute URLs must include the protocol (http:// or https://), complete domain name, and path (such as https://www.example.com/de/page).
Necessity:
- Search engines need to clearly distinguish between different pages. Relative paths (such as
/de/page) may be parsed as any version of the current domain name (such ashttporhttps), causing duplicate content. - When crossing subdomains or subdirectories, not writing the full path will cause engines to misinterpret page ownership (for example,
de.example.com/pageandwww.example.com/de/pagemay be treated as unrelated pages).
- Page has both
httpandhttpsversions, but the protocol is not marked in hreflang, causing authority dilution. - Mobile and desktop pages share content but have different URL structures (such as
m.example.com/deandexample.com/de), not associated using absolute URLs.
Common Error Scenarios and Consequences
Error 1: Relative Paths or Omitted Protocols_ Error Example:<link hreflang="de" href="/de/page" />(relative path)<link hreflang="es" href="www.example.com/es/page" />(missinghttps://)
- Engines may parse
/de/pageashttp://example.com/de/page, while the actual page is thehttpsversion, causing the tag to fail. - Pages with different protocols (HTTP/HTTPS) are treated as independent entities, causing content duplication and authority dilution.
- Error Example: Main site uses
https://example.com/fr/page, but French sub-site useshttps://fr.example.com/page, and hreflang does not mutually point to absolute URLs. - Consequence: Engines cannot establish the association between subdomains and main site pages. French users may be redirected to the default language page.
- Error Example:
<link hreflang="ja" href="https://example.com/page?lang=ja" />(contains tracking parameters) - Consequence: Parameters may be treated as different pages by engines (such as
?lang=jaand?lang=ja&ututm=ads), causing incomplete tag coverage.
Tool Detection Methods
- Google Search Console: In "Coverage Report", check for errors caused by "duplicate pages" or "untagged hreflang" to locate incomplete URLs.
- Screaming Frog:
After crawling the site, filter
hreflangtags and check ifhrefattributes are all absolute URLs (filter conditions://example.comor/path). - Sitebulb: In "International SEO Audit" report, directly mark "Incomplete hreflang URLs" and provide correction suggestions.
Correction Solutions and Practical Steps
CMS System (such as WordPress): Plugin Configuration: If using plugins like Yoast SEO, enable "Generate Absolute URLs" in "Multilingual Settings" (usually requires turning off "Relative Path" option). Database Batch Replace: Using SQL commands or plugins (such as Better Search Replace), replacehref="/ with href="https://www.example.com/.
Manual Code Correction:
In HTML or server-side rendering logic, ensure all hreflang links are concatenated in complete format, for example:
- Force unified protocol: Through
.htaccessor Nginx configuration, automatically redirecthttptohttpsto avoid mixed content. - Canonical URLs: Add 301 redirects for different paths of the same content (such as
/deand/de/) to ensure unique absolute URLs.
Missing Self-Referencing hreflang Tags
For example, if a French page only marks links to other language versions such as English and Spanish, but does not declarehreflang="fr" pointing to itself
Search engines may not be able to confirm the language ownership of the page, causing it to fail proper classification in French users' search results.The Role and Necessity of Self-Referencing Tags_ A self-referencing tag is a required hreflang declaration on a page that points to itself (for example: French page needs to include
<link rel="alternate" hreflang="fr" href="self-URL"/>).
Core Function:
- Clearly define the language/region ownership of the current page to search engines, preventing it from being misclassified as supplementary content for other languages.
- Form a closed-loop association with other language versions (all pages mutually declare), ensuring proper authority transfer.
- Search engines may treat the page as "undeclared language" and default it to the main language directory, causing target user traffic loss.
- In multilingual competition scenarios (such as both English and Spanish pages lack self-referencing), internal duplicate content issues may be triggered.
Common Error Scenarios and Case Analysis
Error 1: Single-Language Site Misusing hreflang- Scenario: A page with only one language version, but forcibly adding hreflang pointing to non-existent other language pages.
- Consequence Example: A page on an English single-language site adds
hreflang="en"pointing to itself while incorrectly linking to non-existenthreflang="es"page, causing engines to determine tag confusion.
- Scenario Example: When using WPML plugin, the "Auto-generate self-referencing hreflang" option was not checked.
- Consequence: Generated tags only contain links to other language versions, lacking declaration for the current page.
- Scenario Example: For pages rendered based on JavaScript (such as React/Vue frameworks), hreflang tags were not properly injected into
<head>. - Consequence: Search engine crawlers may fail to recognize dynamically generated self-referencing tags.
Detection Tools and Methods
Step 1: Manual Source Code Check- Press
Ctrl+Uto view source code, search forhreflang="xx", and confirm whether there is a tag pointing to the current URL (note:xxis the current page language code).
- Enter "URL Inspection Tool", input the page URL, then view the "International Targeting" report - if it shows "Self-referencing hreflang tag not detected", this problem exists.
- After inputting the page URL, the tool will list all associated hreflang links, with red warning marks identifying missing self-referencing tags.
Repair Solutions and Practical Steps
CMS System Repair (using WordPress as example): Plugin Configuration Correction:- If using Yoast SEO: Enable "Add self-referencing hreflang" in "Advanced Settings".
- If using WPML: Go to "Language Settings" → "SEO Options" and check "Include self link".
<head> (using French page as example):
Closed-Loop Association Principle and Necessity_
The core rule of hreflang is that all associated pages must point to each other, forming a complete closed loop. For example:
Solution 2: Manual Code Repair (static sites)
Create an association checklist for each language version (such as Excel), listing all URLs that need mutual linking.
Add tags on pages according to the checklist, for example:
Synchronously modify hreflang on German and French pages to ensure they include English page links.
Solution 3: Server-Side Automation (such as Nginx)
Dynamically generate hreflang tags through reverse proxy and mapping rules:
Solution 3: Server-Side Configuration (such as Nginx)
Dynamically generate Canonical tags matching the current language version:
- German page (
de) needs to point to English page (en), French page (fr), and other language versions; - English page and French page must also point back to the German page.
- Authority Transfer: Closed-loop association helps search engines understand the equivalence of multilingual pages, avoiding authority dilution.
- Prevent Duplicate Content: If only one-way association exists (such as English page points to German page, but German page does not point back to English page), engines may treat them as independent content, triggering duplicate content penalties.
- Single-language pages (such as English only) do not need closed-loop, but require self-referencing.
- Regional variants (such as
en-USanden-GB) should point to each other, but are not required to link to other languages.
Common Broken Link Scenarios and Consequences
Scenario 1: New Language Version Not Synced with Old Pages- Case: A news site adds Japanese page (
ja), but existing English and Chinese pages did not add hreflang tags pointing to the Japanese page. - Consequence: The Japanese page becomes an "isolated page". Search engines only index unassociated other language pages.
- Case: WordPress multilingual plugins (such as Polylang) do not automatically add new language links to old content during batch page generation.
- Consequence: Some page associations are broken. Users visiting old content cannot switch to the newly added language version.
- Case: Spanish page URL contains parameters (such as
?lang=es), but other language pages do not include this parameter in hreflang. - Consequence: Engines treat
esparameter pages and other language pages as unrelated content.
Detection Tools and Troubleshooting Methods
Tool 1: Screaming Frog- In crawl results, go to "Hreflang" tab and filter pages with "Missing Reciprocal Links".
- Operation: Export error list to locate URL groups that failed to form closed loops.
- In "International SEO Audit" report, view "Unreciprocated hreflang links" warnings, which directly show broken-link pages and missing associated languages.
- Set custom rules to monitor associations between multilingual pages, with weekly automatic reports on new broken-link issues.
Repair Solutions and Practical Steps
Solution 1: CMS Plugin Batch Correction (using Shopify as example) Enter multilingual plugin (such as Langify) settings and enable "Auto-associate all language versions" option. In "Template Settings", ensure hreflang tag logic includes looping through all language versions:Conflict with Canonical Tags
For example, if the Canonical tag of a German product page points to the English main site page, engines will consider "German page is just a copy of English page", thus refusing to distribute it to German users. A more common issue is that many CMS systems default all language versions' Canonical to point to the main language page (such asx-default), causing other language pages to fail independent indexing.
Conflict Principle and Priority Rules
Search engines' priority order for processing hreflang and Canonical tags: Canonical Priority: If page A's Canonical points to page B, search engines will consider A as a copy of B. Even if A has hreflang declaration, it will be ignored. hreflang Failure Scenarios:- French page's Canonical points to English page → French page will not be distributed to French users.
- Multilingual pages' Canonical uniformly point to main site → All language versions are treated as duplicate content.
- If the Canonical tag points to itself (i.e.,
<link rel="canonical" href="current page URL"/>), hreflang can work normally.
Typical Error Scenarios and Consequences
Error 1: Multilingual Plugin Default Configuration Conflict- Case: WordPress's Yoast SEO plugin defaults multilingual pages' Canonical to point to the main language page. For example, German page's Canonical tag is
<link rel="canonical" href="https://example.com/en/page"/>. - Consequence: German page is treated as a copy of English page and cannot be displayed in German search results, losing over 50% of traffic.
- Case: URLs with parameters (such as
example.com/page?lang=de) have Canonical pointing to the non-parameter version (example.com/page), but the latter has no hreflang configured. - Consequence: Parameter-containing German pages cannot be indexed. Users only see the default language page when searching.
- Case:
en-USpage's Canonical points to generic English page (en), causing engines to consider American English page has no independent value. - Consequence: US users may be redirected to
enpage (such as British English), reducing localized experience.
Detection Tools and Troubleshooting Methods
Tool 1: Google Search Console- Go to "Coverage Report", filter "Excluded" tags for "Duplicate page" or "Submitted but not indexed" items, and check if hreflang failure is caused by Canonical conflicts.
- After crawling the site, filter pages that simultaneously contain hreflang and Canonical tags, and check if Canonical points to other pages (rather than itself).
- Export data and filter condition:
Canonical != Self-URL.
- Set custom alert rules: Trigger warning when hreflang and Canonical targets are inconsistent.
Repair Solutions and Practical Steps
Solution 1: CMS Plugin Correction (using Yoast SEO as example)- Enter multilingual settings and turn off "Canonical uniformly points to main language" option.
- In "Advanced Settings", enable "Generate independent Canonical tags for each language version".
<head>, ensure the Canonical tag points to its own URL, for example:
Server Errors or Unsupported HTTP Requests
For example, dynamically generated pages fail to load complete HTML due to server timeout, causing hreflang tags in<head> to be missing;
Additionally, mobile pages return 302 temporary redirect instead of 200 status code, and search engines may abandon crawling the tags.
Some CDN or firewall rules block crawler requests, causing language pages for specific regions to be unreadable.
Server Error Types and Impacts
Key Status Codes and Their Consequences: 404 Not Found:- Scenario: A French page is pointed to by other language pages' hreflang, but the actual URL has been deleted or the path is incorrect.
- Consequence: Engines determine hreflang association invalid. French page cannot be indexed, which also reduces credibility of other language pages.
- Scenario: Server crash causes dynamically generated hreflang tags to fail loading.
- Consequence: Page returns 500 error, hreflang completely fails. Crawler may temporarily block the site.
- Scenario: Mobile page temporarily redirects to desktop URL, but does not pass hreflang tags.
- Consequence: Engines may only crawl the target page's (desktop) hreflang, ignoring mobile language versions.
Dynamic Page Loading Issues
JavaScript Rendering Defects:- Case: Single-page applications (SPA) using React/Vue have hreflang tags dynamically inserted via JS, but not pre-rendered.
- Consequence: Search engine crawlers may fail to execute JS, causing hreflang tags to remain unread.
- Case: CDN cache configuration ignores hreflang in
<head>, or caches incorrect language versions. - Consequence: When users visit the same URL, CDN returns cached pages of different languages, causing hreflang association confusion.
- Case: Page load time is too long (>5 seconds), engines terminate crawling early, failing to read complete hreflang tags.
- Consequence: Some language associations are lost, especially affecting large multilingual sites.
Detection Tools and Troubleshooting Methods
Google Search Console:- Use "Coverage Report" to check pages excluded due to server errors (404/500), and filter URLs involving multilingual versions.
- In crawl settings, enable "Check hreflang" option.
- Filter results for "Server error" tags (such as 4xx, 5xx) and view associated hreflang pages.
- Filter search engine crawler (User-Agent contains Googlebot) request records through server logs (such as Nginx's access.log) to locate URLs frequently returning errors.
Repair Solutions and Practical Steps
Repair Server Errors: 404 Issues:- Check if all URLs pointed to by hreflang exist and fix dead links.
- If a page has been deleted, remove that link from other language pages' hreflang.
- Optimize server resources (such as increasing memory, database connection pool) to reduce crash risk.
- Set up monitoring alerts (such as New Relic) to discover and fix issues in real time.
- Use SSR (server-side rendering) functions of frameworks like Next.js and Nuxt.js to ensure hreflang exists when HTML initially loads.
- Configure pre-rendering tools (such as Prerender.io) to provide static versions for crawlers.
- In CDN settings, set language paths like
/de/and/fr/as "no cache" or short cache periods (such as 1 hour). - Ensure CDN passes complete
<head>content and disables HTML tag rewriting.
- Compress page resources (such as images, CSS/JS) and shorten load time to within 3 seconds.
- Use tools (such as Google Lighthouse) to detect and fix render-blocking issues.
Dynamic Parameters Causing Duplicate Content
The abuse of dynamic parameters (such as?utm_source=ads or ?sessionid=123) in URLs is the "invisible promoter" of duplicate content issues on multilingual sites.
For example, a Spanish page may generate multiple URLs due to different parameters (such as /es/page?ref=facebook and /es/page?ref=email). Search engines will treat them as independent pages, causing duplicate content crawling.
Impact and Classification of Parameter Types
Parameters That Must Be Retained:- Pagination parameters (such as
?page=2): Used to distinguish different content blocks. Should be retained but standardized (such as pointing to main page via rel="canonical"). - Language/region parameters (such as
?lang=de): If language is not distinguished by path (such as/de/), these parameters need to be retained and consistent with hreflang.
- Tracking parameters (such as
?utm_source,?ref=social): Do not change page content and should be removed from hreflang. - Session IDs (such as
?sessionid=123): User behavior tracking parameters that easily generate a large number of duplicate URLs.
Common Error Scenarios and Consequences
Error 1: Parameters Not Standardized- Case: The same French page has multiple parameterized URLs (such as
/fr/page?utm=adsand/fr/page?utm=email), all of which are declared as independent pages by hreflang. - Consequence: Search engines crawl multiple duplicate versions, diluting authority, and French page rankings decline.
- Case: English page's hreflang points to
/de/page, but the actual German URL is/de/page?lang=de, causing association breakdown. - Consequence: German page is treated as independent content and cannot form multilingual association with English page.
- Case: Product listing page
/es/products?page=2's hreflang does not point to main listing page/es/products. - Consequence: Pagination may be misjudged as an independent language page, competing for traffic with the main listing page.
Tool Detection Methods
Google Search Console:- Go to "Coverage Report" and filter "Submitted but not indexed" URLs to see if they were excluded due to parameterized duplicates.
- When crawling the site, enable "Ignore URL parameters" option and compare content similarity between parameterized and non-parameterized pages.
- Filter hreflang tags to check if there are parameterized URLs with unstandardized associations.
- In log analysis tools (such as ELK Stack), use regular expressions to filter crawler requests containing specific parameters (such as
utm_*) and count duplicate crawl times.
Solutions and Practical Steps
Solution 1: Parameter Standardization (Server Configuration)_ Apache Rule Example:- Function: Automatically remove all
utm_parameters and 301 redirect to non-parameter URLs.
/de/page).
Add Canonical tags to parameterized URLs pointing to non-parameter versions:
- Go to "URL Parameters" settings and mark parameters like
utm_andsessionidas "No effect on page content". - Mark pagination parameters (such as
page) as "Paginates" to help engines understand their function.
hreflang optimization for multilingual sites is by no means "configure once, use forever" Perfecting the details often starts with avoiding these "insignificant" technical errors.