Backend issues in Algolia's Magento Open Source and Adobe Commerce extension

The first thing to do if you encounter an issue is to ensure your Algolia Magento Open Source and Adobe Commerce extension is up to date. A new release may have fixed your issue, and you’ll also benefit from improvements to the extension’s performance and security.

To check the extension’s version, check the GitHub repository. Compare this version to the version stated in the etc/module.xml file in your Magento installation:

You can also check for updates from Algolia’s dashboard. Find the API clients using your indices by going to Monitoring > Operations > API Client. If a new version is available, it will be displayed next to the version in use.

To update the extension, read the upgrading guide.

Understand how your Magento configuration determines the number of indices to create

You must add your account credentials when setting up the extension for the first time. The extension will then automatically add all the indices your account requires. You can check which indices have been created from Algolia’s dashboard if you wish.

Sorting

By default, the extension creates three replicas for each product index. These replicas are directly related to the sorting configuration in the InstantSearch section.

Modifying sorting directly affects the number of records created.

Indices

Algolia’s dashboard provides insight into how the Magento extension uses indices.

Indices created by the extension depend on how Magento configures indices for products, categories, and additional sections. The index name is influenced by the index name prefix defined in the Magento configuration.

If you use the extension in production, you probably want to use it in an acceptance/staging or development environment. Defining meaningful prefixes to identify instantly “which index belongs to which environment” is good practice, resulting in indices like prod_magento, staging_magento, and dev_magento.

The first step to successful indexing is to perfect your Magento configuration. This way, it’s easier to anticipate the number of indices created. If the number of indices is incorrect, something may be wrong with your Magento configuration.

Incorrect configuration

The following are examples of Magento configurations that can lead to an unexpected number of indices.

Different configuration on store view or website level

Magento allows users to define a default configuration and a configuration for a specific store view or website. You can configure some extension settings this way too.

For example, you can sort differently on two websites in the same Magento installation, creating a different number of indices for these two websites. Since Magento only displays the default configuration when landing on the settings page, this manual configuration is easy to overlook, especially with more than one administrator.

If an unexpected number of indices is created, ensure no unwanted configuration has been set by switching from the default settings to a store view or a website-specific configuration.

All stores configuration

The extension adheres to Magento’s list of websites, stores, and views. Find these by going to Stores > Settings > All Stores.

If you have a multilingual webshop that uses the extension, every language needs its own indices, and the total number of indices can significantly increase because of this.

Customer group configuration

By default, Magento creates a set of four customer groups: General, Not logged in, Retailer, and Wholesale. Third-party extensions can create their own customer groups in the Magento installation, sometimes even hundreds of them.

The extension allows you to manage customer groups in the advanced section of the configuration. Be careful when enabling this feature: every customer group will create new indices. If a third-party extension creates hundreds of customer groups, Algolia’s extension will create hundreds more indices per store view.

Out of sync data

If it seems like data isn’t being pushed to Algolia’s servers:

1. An error may have occurred during the indexing process: investigate the logs
2. If the indexing queue is turned on, there could be a queue processing problem
3. The product or category being indexed has a particular status preventing it from being indexed.

Read about the requirements for a product or category to be indexed in the indexing guide.

Debugging missing products or categories

If your data isn’t showing up but meets the requirements listed on the indexing page:

1. Go to the Magento back-office and find the product or category missing.
2. Save the item without changing anything. This should trigger the Magento save event and send any data that requires updating to Algolia’s servers. This also works if the indexing queue is turned off.
3. Go to Algolia’s dashboard.

4. Check if the extension has updated the product or category. Find the index, look up the product/category and check the algoliaLastUpdateAtCET attribute. This attribute contains the date and time the records were updated (Central European Time).

   

5. If products are still out of sync, check the logs on Algolia’s dashboard: go to API Monitoring > Search API Logs. Reindexing triggers a POST request that should appear at the top of the list. The URL should be something like /1/indexes/[INDEX_NAME]/batch. By clicking the link, the request details will show up. The extension successfully sent the record to Algolia’s servers if you can see the attributes in the Request body tab (under the AddObject action).

   

6. If the attributes aren’t updated, and the algoliaLastUpdateAtCET attribute in the index’s object isn’t updated, use the SKU reindexing form. This form gives you feedback on why the product hasn’t updated.

Third-party extensions

The extension uses Magento’s plug-in system to apply Algolia’s logic to the following Magento classes:

• Magento\Catalog\Model\ResourceModel\Product
• Magento\Catalog\Model\Product\Action
• Magento\CatalogInventory\Model\ResourceModel\Stock\Item
• Magento\Catalog\Model\ResourceModel\Category
• Magento\Catalog\Model\Category\Action

Any third-party extension that updates resources without triggering Magento’s save events on the preceding classes will break the real-time updating of the catalog. To fix this, you must manually trigger reindexing.

Updates aren’t sent to Algolia

If the data in Algolia’s dashboard has unexpected values, look at the attributes specific to the store view or website. The extension respects settings set at the store view and website level, which may override the default settings. To check if this is the case, change the view to show the store view or website setting by using Magento’s store switcher (top-left corner of the window).

Investigate the logs

First, figure out if your indexing process generates errors. Since the process can be asynchronous, errors can happen without you being aware.

During the asynchronous indexing process, the extension generates temporary indices suffixed by _tmp. For example, if the main product index is magento_products_default, the extension will generate an index named magento_products_default_tmp.

The temporary indices are created to do an atomic reindex to prevent production indices from being corrupted.

Because the temporary index is only swapped after the whole process completes, if there is an error, the temporary index will still exist. Check Algolia’s dashboard to see if any indices end with a _tmp suffix and haven’t been updated in a while.

All errors are logged by default in Magento. The var/log folder in the Magento installation contains two log files:

• system.log
• exception.log

If you want to see if anything gets logged during the indexing process, run the following command from the terminal (from the root folder of the Magento installation) before re-running the indexing process again:

$
tail -f var/log/system.log var/log/exception.log

The error messages in the log will help you pinpoint the issue’s source.

You can also request more detailed logging during the indexing process.

The queue may be stuck

If the data in your index isn’t up-to-date, your indexing queue may be stuck. The queue relies on one of Magento’s indexers, added by the extension: the algolia_queue_runner.

Ensure the Magento indexer is “ready” by running the following in the command line:

$
php bin/magento indexer:status algolia_queue_runner

If the status of the queue is “processing” for a long time, it may need to be reset by running the following in the command line:

$
php bin/magento indexer:reset algolia_queue_runner

Monitoring the queue

From version 1.8 of the extension, there’s a monitoring page (at Stores > Algolia Search > Indexing Queue). This page contains a grid displaying the contents of the indexing queue. It lets you monitor the number of operations the queue needs to perform.

You can see details of each operation by clicking the ‘view’ link. Any error occurring during the job is logged in the Error Log attribute.

At the top of the page, the recommendations section helps you configure and optimize the queue in the best way possible.

If the indexing queue performs as expected, the number of jobs should decrease every 5 minutes (don’t forget to refresh the page). If the number of operations doesn’t decrease, ensure that the queue is correctly set up.

From version 1.8 of the extension, any failing operation that reached the maximum number of retries is archived in the algoliasearch_queue_archive table. This is another good place to check for error logs since the last encountered error is stored along with the job.