Advanced Breadcrumbs Troubleshooting Guide

Symptoms:

• No breadcrumbs visible on any page
• Breadcrumbs still look like default Magento (JavaScript-based)

Solution:

1. Verify the module is enabled in configuration (see Quick Diagnostics)
2. Confirm the module is registered: bin/magento module:status should list Magmodules_AdvancedBreadcrumbs as enabled
3. Clear all relevant caches: config, layout, full_page
4. If using Varnish or an external cache layer, purge that as well
5. Check if another module is also overriding the breadcrumbs block — conflicts can silently prevent rendering

Prevention:

• Always clear full page cache after configuration changes

Symptoms:

• Breadcrumbs appear on category pages but not product pages, or vice versa
• No breadcrumbs on CMS pages, search results, or other page types

Solution:

1. Go to the Page Types section in configuration
2. Check which page types are enabled — only selected types will render breadcrumbs
3. The default configuration enables only Category, Product, and CMS pages — other types must be explicitly enabled
4. Save the configuration and clear cache

Symptoms:

• Product breadcrumb shows an unexpected category path
• A "Sale" or other marketing/seasonal category appears instead of the expected structural category

Solution:

1. Check if the product has a "Primary Breadcrumb Category" override set (in product edit > SEO section). If set, this takes priority over all other logic.
2. Adjust category weights: navigate to the category you want to appear and set a positive weight (e.g., 10). On the unwanted category, set weight to -1.
3. Review the Selection Strategy in configuration. "Deepest Path" generally gives the best results for standard catalog structures.
4. Confirm the desired category is active, visible in menu, and the product is assigned to it.

Prevention:

• Set negative weights on marketing and seasonal categories upfront, before products are assigned
• Test with a representative set of products after changing the selection strategy

Symptoms:

• No BreadcrumbList JSON-LD block in the page source
• Google Search Console reports missing breadcrumb structured data

Solution:

1. Check the Structured Data section in configuration — "Enable JSON-LD" must be set to Yes
2. View the raw page source (Ctrl+U, not browser DevTools) and search for BreadcrumbList
3. If breadcrumbs are rendering visually but JSON-LD is absent, the structured data toggle may be off independently
4. If JSON-LD is present but Google does not recognize it, validate using Google's Rich Results Test tool

Prevention:

• Validate structured data after initial setup using the Google Rich Results Test or the Schema.org validator

Symptoms:

• Two or more BreadcrumbList JSON-LD blocks appear in the page source
• Google Search Console reports "duplicate structured data" warnings

Solution:

1. Another module is likely also outputting breadcrumb JSON-LD — common culprits are rich snippets modules and general SEO modules
2. Disable the breadcrumb structured data output in the other module
3. Use Advanced Breadcrumbs as the single source of breadcrumb JSON-LD output

Symptoms:

• Breadcrumbs render but styling is broken or absent
• Missing Tailwind utility classes
• Breadcrumbs appear unstyled or use default HTML without classes

Solution:

1. The module auto-detects Hyva and switches to Hyva-specific templates. Confirm that Hyva_Theme is enabled.
2. Run the Tailwind CSS build for your Hyva setup (typically npm run build or equivalent) — the module's Hyva template classes need to be picked up during the CSS purge/scan step
3. The module registers itself for Hyva's Tailwind content scan via the RegisterHyvaConfig observer. If styles are still missing, verify that tailwind.config.js includes the module's template path.

Symptoms:

• The Home breadcrumb links to the wrong store view or base URL
• Occurs primarily in multi-store setups with different base URLs per store view

Solution:

1. The Home breadcrumb URL is derived from Magento's store base URL. Check Stores > Configuration > General > Web > Base URLs
2. In a multi-store setup, make sure each store view has the correct Base URL configured at the store view scope
3. Clear the config cache after any base URL changes

Symptoms:

• A weight value is entered on a category, saved, but reverts to 0 on reload
• The weight field is not visible in the category edit form

Solution:

1. The weight field is located in the "Search Engine Optimization" section of the category edit form
2. Confirm you are saving at the correct scope — if the field is set at store view level, switch to the correct store view before saving
3. If the field is not visible at all, the data patch may not have run — execute bin/magento setup:upgrade to apply it
4. Check if the "Exclude from Breadcrumbs" toggle is set on the category — this overrides the weight entirely