Skip to content
Adobe Commerce Storefront
Troubleshooting

Frequently Asked Questions (FAQ)

Where can I find technical documentation?

What should I do if my Catalog Service/Live Search data is missing or corrupted?

Submit a request to Adobe Commerce Support to clear your data space. This deletes all data within Catalog Service/Live Search for a specific environment ID. Be careful not to clear any data space required for production.

After Adobe Commerce Support clears your data space, you can re-synchronize it using the following commands:

bin/magento saas:resync --feed scopesCustomerGroup --cleanup-feed
bin/magento saas:resync --feed scopesWebsite --cleanup-feed
bin/magento saas:resync --feed productattributes --cleanup-feed
bin/magento saas:resync --feed variants --cleanup-feed
bin/magento saas:resync --feed products --cleanup-feed
bin/magento saas:resync --feed productoverrides --cleanup-feed
bin/magento saas:resync --feed prices --cleanup-feed
bin/magento saas:resync --feed categories --cleanup-feed
bin/magento saas:resync --feed categoryPermissions --cleanup-feed

See the SaaS Data Export Guide for more information.

How can I improve the performance of my catalog pages?

Images

  • Product images should be delivered in the appropriate size and should not be delivered larger than their rendered size. Use Fastly Image Optimizer where possible to deliver images in modern .webp format.
  • Use loading="eager" on largest contentful paint (LCP) relevant images and loading="lazy" on images with lower priority. Be aware that these attributes are a hint only for the browser.

API

  • Blocks that load data from APIs must have proper sizing in their loading state to prevent layout shift when they start to render content.
  • API endpoints should be proxied through a content delivery network (CDN) to prevent overhead of cross-origin resource sharing (CORS) (OPTIONS calls) and TLS handshakes.
  • Start GraphQL queries early (for example, in eager phase)

Preloading

  • Frequently used commerce.js and configs.js files can be loaded early by adding them to the head.html file.
  • Remove waterfall loading of files. If you know in advance which files are required, load them early or combine them to load fewer files.
  • You can preload resources/queries in the eager phase of the scripts.js file if they are very heavy. You can use global promises or a link tag with preload attribute in the head to prevent downloading the same resource multiple times.

Loading order

  • Everything that is not relevant for LCP can be loaded progressively (dynamic imports) or delayed (delayed.js).
  • LCP relevant blocks (for example, product details, product list page) must be loaded in the eager phase. This means that they need to be the first block on the page and added to the LCP_BLOCKS array.
  • Only load elements that are required. Elements that are not immediately required should be separated and loaded when needed.
    • Example 1: Logic for newsletter sign-up can be loaded when the user clicks on the subscribe button.
    • Example 2: Minicart block is loaded on every page but only loads lightweight code to display button and a number. The full minicart block is loaded only upon a click of the button.

Libraries

Use Preact/HTM or other libraries only when necessary.

Thid-party integrations

  • Prefer APIs over embedding third-party scripts.
  • If you must embed third-party scripts, try using placeholders to prevent cumulative layout shift (CLS). Load them delayed or when they appear in the viewport (IntersectionObserver).
  • Be careful with how you add fonts to the project. Ideally, you should avoid using fonts hosted by third parties.

How do I deploy custom VCLs to Fastly?

See Getting started with custom VCL in the Commerce on Cloud Infrastucture Guide.

By default, Adobe Commerce email templates (such as “Forgot Password” and “Create Password”) use camelCase in their route URLs (for example, /customer/account/forgotPassword). However, Helix 5 and Edge Delivery Services only support lowercase routes (for example, /customer/account/forgotpassword). This incompatibility means that links in default email templates will not work correctly on Commerce Storefronts powered by Edge Delivery Services.

To fix this issue, you can customize email templates to use the following workaround:

Create a custom email template for the “Forgot Password” and “Create Password” pages

  1. Log in to the Commerce Admin.

  2. On the Admin sidebar, go to Marketing > Communications > Email Templates.

  3. Click Add New Template.

  4. In the Load default template section, click the Template selector and choose Magento_Customer > Forgot Password.

  5. Click Load Template.

    The HTML code and variables from the template appear in the form.

  6. Enter the Template Name. For example, “Forgot Passsword - Edge Delivery Services”.

  7. In the Template Content field, change any camelCase or capitalized route URLs to all lowercase. See the following screenshot for an example.

    Forgot Password template

  8. Click Save Template.

Update the configuration

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. Click Customers > Customer Configuration.

  3. Expand the Password Options section.

  4. Set Forgot Email Template to the custom template that you created in Step 1. See the following screenshot for an example.

    Forgot Password template

  5. Click Save Config.

Why don’t I see my configuration changes in the browser?

The storefront configuration is cached by the Edge CDN with a max-age=7200 (2 hours) cache control header.

When the storefront configuration is loaded in the browser, it is stored in session storage. This means that the configuration persists until the browser session is cleared, or the page is refreshed after the expiration of the CDN cache. You can verify the current configuration by accessing <site.com>/config.json directly in your browser. This will show you the current configuration being served by the CDN.

For developers: If your configuration changes are not reflected in the browser, check for CDN cache expiration by accessing <site.com>/config.json directly in your browser. If the updated configuration is available on the CDN, manually clear the session storage:

  1. Open the browser developer tools.
  2. Select the Application tab, then select Storage.
  3. Clear the session storage for your domain.
  4. Refresh the page.

For end users: Clear the browser session by closing and reopening the browser, or clear the browsing data to see configuration changes.