Troubleshooting FAQ Manager Issues

Symptoms:

• Visiting the FAQ page URL shows a 404 Not Found page
• The page exists in the admin and is set to active

Solution:

1. Verify the URL key matches what you're visiting (e.g., URL key faq = yourstore.com/faq)
2. Check that the page is set to Is Active: Yes
3. Check that the module is enabled in the configuration
4. Clear the full page cache: System → Cache Management → Flush Full Page Cache
5. If using Varnish, purge the Varnish cache as well

Prevention:

• Always test the URL immediately after creating a new page
• Avoid URL keys that conflict with existing CMS pages, categories, or product URLs

Symptoms:

• Product page loads normally but no FAQ section appears
• FAQs are linked to the product in the admin

Solution:

1. Verify Enable FAQs on Product Pages is set to Yes in module configuration
2. Check that the FAQ is set to Is Active: Yes
3. Confirm the product link exists: edit the FAQ → Products tab → verify the product appears in the selected products list
4. Clear the block HTML and full page cache
5. Check your theme's catalog_product_view.xml for any layout overrides that might remove the FAQ block

Prevention:

• After linking FAQs to products, always verify on the frontend

Symptoms:

• Category page loads but no FAQ section appears
• FAQs are linked to the category in the admin

Solution:

1. Verify Enable FAQs on Category Pages is set to Yes in module configuration
2. Check that the FAQ is set to Is Active: Yes
3. Confirm the category link: edit the FAQ → Catalog Categories tab → verify the category is selected
4. Clear caches

Prevention:

• Same as product FAQs — always verify on the frontend after making changes

Symptoms:

• FAQs display correctly on the page but no structured data is visible in the page source
• Google's Rich Results Test doesn't detect FAQPage markup

Solution:

1. View the page source (not just inspect element) and search for FAQPage
2. Make sure you're looking at the actual frontend page, not a cached version
3. Verify the FAQs are rendering inside the correct template (check that the design theme matches your frontend theme)
4. If using a CDN or cache layer, ensure it's not stripping schema markup

Prevention:

• After initial setup, always validate with Google's Rich Results Test

Symptoms:

• Switching store views shows the same language for all views
• Translated content doesn't appear on the frontend

Solution:

1. Verify you entered translations in the correct store view scope (switch to the store view in the admin, then edit the entity)
2. Check that the store view scope is correct — translations are entered at the store view level, not website level
3. Clear the configuration and full page cache
4. Verify the fallback: if no store-specific translation exists, the default (All Store Views) content is used — this is expected behavior

Prevention:

• Always create content in All Store Views first, then add translations per store view
• After adding translations, check the frontend in each store view

Symptoms:

• The FAQ page renders with the title and optional intro text, but no FAQ accordions appear

Solution:

1. Check the Assigned Topics tab on the page — at least one topic must be assigned
2. Verify the assigned topic(s) are set to Is Active: Yes
3. Verify the topic(s) have active FAQs assigned to them
4. Check the topic position values — they should be numeric

Prevention:

• A page needs: active page → active topic(s) assigned → active FAQ(s) in those topics. All three levels must be active for content to appear.

Symptoms:

• Using "With Topic Icons" design but icons don't appear
• Icon upload succeeds in admin but no image on frontend

Solution:

1. Verify you selected a design theme that includes icons (Hyva - With Topic Icons or Luma - With Topic Icons)
2. Check that the icon was uploaded successfully — edit the topic and verify the icon preview is visible
3. Verify the icon file exists in pub/media/faq/topic/icon/
4. Check file permissions on the media directory

Prevention:

• Use SVG format for best compatibility and quality
• Keep icon files under 2 MB