Troubleshooting

Having issues with the Alternate Hreflang Extension? This page covers the most common problems and how to fix them. Start with the quick diagnostics section to narrow down what's wrong, then jump to the relevant issue. We've also included debugging tips (debug mode, log files, self-test) and what to check when things aren't working as expected.

Common problems and how to fix them.

Quick Diagnostics

Before diving into specific issues, run these quick checks:

1. Check module is enabled

   • Stores → Configuration → Magmodules → Alternate Hreflang → General → Enable: Yes

2. Clear cache

   bin/magento cache:flush
   

3. Run self-test

   • Stores → Configuration → Magmodules → Alternate Hreflang → Debug & Logging
   • Click "Run Self-Test" button

4. Check logs

   tail -n 50 var/log/error.log | grep AlternateHreflang
   tail -n 50 var/log/debug.log | grep AlternateHreflang
   

5. Test with debug mode

   • Enable: Alternate Hreflang Configuration → Enable Debug Mode: Yes
   • Visit: https://example.com/page?show-alternate=1

---

Common Issues

Issue: Hreflang Tags Not Appearing

Symptoms:

• No hreflang tags in page source
• Empty output when using ?show-alternate=1
• Tags missing from specific page types

Solution:

1. Verify module is enabled:

   • General → Enable: Yes

2. Check page type is enabled:

   • For homepage: Configuration → Enable on Homepage: Yes
   • For products: Configuration → Enable on Product Pages: Yes
   • For categories: Configuration → Enable on Category Pages: Yes
   • For CMS: Configuration → Enable on CMS Pages: Yes

3. Verify store targeting is configured:

   • Targeting Settings → Check stores are added with language codes
   • At least 2 stores must be in the same group

4. Clear cache:

   bin/magento cache:flush
   

5. Check canonical integration:

   • If "Enable Hreflang Only on Canonical URLs" is enabled
   • Verify page has self-referential canonical tag

6. Check NoIndex handling:

   • If NoIndex handling is enabled
   • Verify page doesn't have noindex directive

Prevention:

• Run self-test after configuration changes
• Test with ?show-alternate=1 before going live
• Keep debug mode enabled until verified

---

Issue: Wrong URLs in Hreflang Tags

Symptoms:

• Hreflang tags point to incorrect URLs
• URLs for wrong store-views
• 404 errors on alternate URLs

Solution:

1. Check store base URLs:

   • Stores → Configuration → Web → Unsecure/Secure → Base URL
   • Verify each store has correct base URL

2. Verify store targeting configuration:

   • Check language codes match expected stores
   • Verify group numbers are correct

3. Check product/category exists in all stores:

   • Product must be enabled in all stores in the group
   • Category must be active in all stores

4. Test URL generation:

   • Enable debug mode
   • Check logs for URL generation: grep "Adding hreflang" var/log/debug.log

5. Clear cache and reindex:

   bin/magento cache:flush
   bin/magento indexer:reindex
   

Prevention:

• Verify base URLs are correct for each store
• Ensure products/categories are enabled in all target stores
• Test URLs manually before deploying

---

Issue: Hreflang Tags on Filtered/Duplicate Pages

Symptoms:

• Tags appear on URLs like /product?color=red
• Tags on paginated pages like /category?p=2
• Duplicate hreflang signals

Solution:

1. Enable canonical integration:

   • Configuration → Enable Hreflang Only on Canonical URLs: Yes

2. Verify canonical tags are set:

   • Filtered pages should have canonical pointing to main page
   • Check page source for <link rel="canonical" ...>

3. Clear cache:

   bin/magento cache:flush
   

4. Test:

   • Visit filtered URL with ?show-alternate=1
   • Hreflang tags should NOT appear
   • Visit canonical URL with ?show-alternate=1
   • Hreflang tags SHOULD appear

Prevention:

• Always enable canonical integration
• Ensure Magento canonical tags are working correctly

---

Issue: Hreflang on NoIndex Pages

Symptoms:

• Tags appear on pages with noindex directive
• Mixed signals to search engines
• SEO issues

Solution:

1. Enable NoIndex handling:

   • Configuration → Enable NoIndex Handling: Yes

2. Configure attributes/columns:

   • Product Attribute: Select correct attribute (e.g., mm_meta_robots)
   • Category Attribute: Select correct attribute
   • CMS Column: Enter correct column name

3. Verify attribute values:

   • Check product/category attribute contains NOINDEX
   • For CMS, check database column value

4. Clear cache:

   bin/magento cache:flush
   

5. Test:

   • Visit noindex page with ?show-alternate=1
   • Hreflang tags should NOT appear

Prevention:

• Enable NoIndex handling from the start
• Use consistent attribute names across entities
• Test with noindex pages after configuration

---

Issue: Missing Store-Views in Hreflang

Symptoms:

• Some stores don't appear in hreflang tags
• Expected 4 languages but only 2 show up
• Inconsistent tags across pages

Solution:

1. Check store targeting configuration:

   • Verify all stores are in the same group number
   • Check language codes are entered correctly

2. Verify stores are enabled:

   • Stores → All Stores
   • Check each store is enabled

3. Check product/category availability:

   • Entity must be enabled in all stores
   • Visibility must be appropriate

4. Verify base URLs:

   • Each store must have a valid base URL
   • URLs must be accessible

5. Run self-test:

   • Check for warnings about store configuration

Prevention:

• Double-check group numbers when configuring
• Test with a product that exists in all stores
• Run self-test after adding new stores

---

Issue: Performance Problems

Symptoms:

• Slow page load times
• High server load
• Sitemap generation timeouts

Solution:

1. Disable debug logging:

   • Debug & Logging → Debug Mode: No (in production)

2. Check number of stores:

   • Large number of stores increases processing
   • Consider if all stores need hreflang

3. Review sitemap configuration:

   • Disable sitemap integration if not needed
   • Generate sitemaps during off-peak hours

4. Enable caching:

   • Ensure full-page cache is enabled
   • Verify block cache is working

5. Monitor logs for slow queries:

   grep "slow" var/log/debug.log
   

Prevention:

• Only enable needed page types
• Keep debug logging disabled in production
• Monitor performance after configuration changes

---

Issue: X-Default Configuration Not Working

Symptoms:

• X-default tag not appearing
• X-default points to wrong page
• Errors in Search Console

Solution:

1. Verify x-default is configured:

   • Targeting Settings → X-Default Configuration
   • Check either CMS page or store-view is selected

2. For CMS page option:

   • Verify CMS page exists
   • Check page is enabled
   • Verify URL is accessible

3. For store-view option:

   • Verify store is enabled
   • Check store is in a group with other stores

4. Test output:

   • Use ?show-alternate=1 to verify x-default tag

Prevention:

• Keep x-default simple (skip for simple setups)
• Test x-default configuration before deploying
• Consult SEO partner for complex setups

---

Issue: Self-Test Failures

Symptoms:

• Self-test shows errors or warnings
• Configuration issues detected
• Compatibility problems

Solution:

1. Review self-test results carefully

   • Read each error/warning message
   • Prioritize errors over warnings

2. Common self-test issues:

   "No stores configured"

   • Add stores to targeting configuration

   "Invalid language code"

   • Use lowercase with hyphen: en-us not en_US

   "Store base URL missing"

   • Configure base URL in Stores → Configuration → Web

   "No page types enabled"

   • Enable at least one page type in Configuration

3. Fix issues and re-run test

4. Check compatibility warnings

   • Update incompatible modules
   • Check Magento version requirements

Prevention:

• Run self-test before going live
• Run self-test after major configuration changes
• Run self-test quarterly for maintenance

---

Issue: Sitemap Integration Not Working

Symptoms:

• Hreflang not appearing in sitemap.xml
• Sitemap generation errors
• Missing xhtml:link elements

Solution:

1. Verify requirements:

   • Magmodules Sitemap and Robots module installed
   • Third Party Support enabled

2. Check sitemap configuration:

   • Third Party → Sitemap Products/Categories/etc.: Yes
   • Corresponding page type must also be enabled

3. Regenerate sitemap:

   • Marketing → SEO & Search → Sitemap
   • Generate new sitemap

4. Verify sitemap output:

   curl https://example.com/sitemap.xml | grep "xhtml:link"
   

5. Check sitemap logs:

   grep "sitemap" var/log/system.log
   

Prevention:

• Regenerate sitemap after configuration changes
• Test sitemap locally before submitting to search engines
• Monitor sitemap file size for large catalogs

---

Debug Mode Usage

Enable Debug Logging

Purpose: Detailed logs for troubleshooting

How to enable:

1. Debug & Logging → Debug Mode: Yes
2. Clear cache
3. Reproduce issue
4. Check logs: tail -f var/log/debug.log | grep AlternateHreflang

What to look for:

[AlternateHreflang] Generating hreflang tags for product ID: 123
[AlternateHreflang] Found 3 store-views in group 1
[AlternateHreflang] Adding hreflang: en-us → https://example.com/product

Disable after: Always disable debug logging in production

---

Enable Frontend Debug

Purpose: View hreflang tags directly in browser

How to enable:

1. Alternate Hreflang Configuration → Enable Debug Mode: Yes
2. Visit any page with ?show-alternate=1
3. View generated tags and configuration

Disable after: Disable before going live

---

Google Search Console Errors

"No Return Tag" Error

What it means: Store A links to Store B, but Store B doesn't link back to Store A

Solution:

• Verify both stores are in the same group
• Check both stores have the product/category/page
• Ensure configuration is symmetrical

---

"Incorrect Language Code" Warning

What it means: Language code doesn't match ISO standard

Solution:

• Use proper format: en-us not en_US
• Check for typos in language codes
• Use standard codes from Best Practices

---

"Multiple X-Default Tags" Error

What it means: More than one x-default tag on the page

Solution:

• Check x-default configuration
• Verify no other modules are adding x-default
• Use only one x-default strategy

---

Need More Help?

If you've tried the solutions above and still experience issues:

Documentation:

• All Help Articles - Complete documentation overview

Support:

• Contact Support - Get help from our team

When contacting support, include:

• Module version
• Magento version
• Self-test results (Admin → Magmodules → Alternate Hreflang → Developer → Self-Test)
• Steps to reproduce the issue
• Any error messages from logs