Picture for Overcome issues with Magento 2
Picture by Matt Chad

This article provides answers to questions about the most common and less known bugs that you may encounter while developing Magento 2. The developer experience is improving with every release. However, there are still many error messages that are cryptic, mysterious and unclear.

The problem list is constantly updated as new features are added all the time.

Missing di.xml configuration argument

When happens:

  • bin/magento setup:upgrade
  • bin/magento setup:di:compile
Notice: Undefined index: value in /var/www/html/vendor/magento/framework/Data/Argument/Interpreter/DataObject.php on line 37

Solution to Undefined index: value

Check for missing item config in the module di.xml file. Example of invalid Magento 2 configuration:

<type name="Magento\Framework\Console\CommandListInterface">
        <argument name="commands" xsi:type="array">
            <item name="lucid-modules-kustom-command" xsi:type="object"></item>

As you might have noticed, the XML node lucid-modules-kustom-command is empty. Provide a fully qualified name to the class that should be injected as the object parameter.

Unsupported ElasticSearch or OpenSearch version

After indexing a fresh Magento installation with bin/magento index:reindex you encounter a following error:

bin/magento index:reindex
Catalog Search index process unknown error:
{"error":"no handler found for uri [/magento2_product_1_v1/document/_mapping] and method [PUT]"}

Solution to Magento 2 "no handler found for uri" error

Magento 2.4.5 and previous versions do not support ElasticSearch 8 and OpenSearch 2. Downgrade ElasticSearch to version 7.* or switch OpenSearch to version 1.*.

Magento 2 cluster block exception on reindex

When you execute Magento upgrade or reindex commands, you might get an error: cluster_block_exception [TOO_MANY_REQUESTS]. ElasticSearch or OpenSearch may return trace similar to the following:

    "error": {
        "root_cause": [
                "type": "cluster_block_exception",
                "reason": "index [magento2_product_2_v1090] blocked by: [TOO_MANY_REQUESTS/12/index read-only / allow delete (api)];"
        "type": "cluster_block_exception",
        "reason": "index [magento2_product_2_v1090] blocked by: [TOO_MANY_REQUESTS/12/index read-only / allow delete (api)];"
    "status": 429

Solution to Magento 2 cluster block exception

Free ElasticSearch instance disk space or disable the allocation threshold with curl request.

curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_cluster/settings -d '{ "transient": { "cluster.routing.allocation.disk.threshold_enabled": false } }'
curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_all/_settings -d '{"index.blocks.read_only_allow_delete": null}'

Magento 2 theme is not displayed

You develop for Magento 2 on local environment and theme is not displayed. This might be caused by running bin/magento setup:upgrade before you have downloaded theme files.

Result of running 'SELECT * FROM theme' query

Solution to invisible Magento 2 theme

Update the type column to 0 in Magento 2 theme table .

Import fails with Error in data structure: entity values are mixed

This error is caused by failed imports. Magento 2 keeps imported rows in importexport_importdata table to ensure unique ID for each row.

Magento 2 maximum error count reached import error

Solution to Magento 2 Error in data structure

Get rid of stale import data and truncate the table importexport_importdata using the following SQL command:

TRUNCATE importexport_importdata;

Remember to add an appropriate prefix if your database tables have one.