Magento 2 OpenSearch Setup and Tuning Guide for 2.4.8

Since 2.4, Magento cannot run without a search engine. Catalog search, category listing and layered navigation all read from it, so a slow or unhealthy OpenSearch cluster shows up as slow category pages, empty search results and failed reindexes. This guide covers how I set up OpenSearch for Magento Open Source and Adobe Commerce 2.4.8, the settings that matter, and how to check what is going on when something breaks.

Which engine and version

For 2.4.8 the recommended engine is OpenSearch 2.x. Adobe publishes the exact tested versions on the system requirements page for each release, and I check that page before every upgrade instead of relying on memory. Running a newer major version than the one tested is a common source of mapping errors during reindex.

In Magento the engine is selected by the catalog/search/engine config value. For OpenSearch the value is opensearch. If you upgraded an older store that used Elasticsearch, check this value first, because a leftover engine setting gives errors that look like connection problems.

Connecting Magento to OpenSearch

On a fresh install the connection is passed to setup:install:

bin/magento setup:install \
  --search-engine=opensearch \
  --opensearch-host=opensearch \
  --opensearch-port=9200 \
  --opensearch-index-prefix=magento2 \
  --opensearch-timeout=15 \
  --opensearch-enable-auth=1 \
  --opensearch-username=magento \
  --opensearch-password=CHANGE_ME
  # plus your usual database, admin and base URL options

On an existing store use config:set. I prefer to lock these values in app/etc/env.php with the --lock-env flag, so each environment keeps its own host and nobody changes it from the admin by mistake.

bin/magento config:set --lock-env catalog/search/engine opensearch
bin/magento config:set --lock-env catalog/search/opensearch_server_hostname opensearch
bin/magento config:set --lock-env catalog/search/opensearch_server_port 9200
bin/magento config:set --lock-env catalog/search/opensearch_index_prefix magento2
bin/magento config:set --lock-env catalog/search/opensearch_server_timeout 15
bin/magento cache:flush config

The admin has a Test Connection button under Stores, Configuration, Catalog, Catalog, Catalog Search. It only proves that Magento can reach the cluster. It says nothing about index health.

Index prefix on shared clusters

If more than one Magento instance points at the same cluster, for example staging and a feature environment, give each one its own index prefix. Two stores writing to the same prefix overwrite each other's product indexes and the symptoms are random: products from the wrong catalog, missing results after a reindex on the other environment.

How Magento names its indexes

Magento creates one product index per store view. The physical index has a version suffix and an alias points to the live one. During a full reindex Magento builds a new index, then moves the alias and deletes the old one. That means a full reindex needs room for two copies of each store's index at the same time. Keep that in mind when sizing disk.

curl -s 'http://opensearch:9200/_cat/indices?v&s=index'
curl -s 'http://opensearch:9200/_cat/aliases?v'
curl -s 'http://opensearch:9200/_cluster/health?pretty'

These three calls answer most questions. Indexes with your prefix should be listed, each store view should have an alias, and cluster health should be green.

Server settings that matter

JVM heap

OpenSearch runs on the JVM and heap size is the setting with the biggest effect. Set minimum and maximum to the same value in config/jvm.options or through OPENSEARCH_JAVA_OPTS. The usual guidance is about half of the machine's memory, leaving the rest to the operating system file cache, and staying below roughly 31 GB so the JVM can keep using compressed pointers.

-Xms2g
-Xmx2g

Most catalogs I see do not need a huge heap. A few hundred thousand products across a handful of store views fit in a few gigabytes. When heap is too small you see long garbage collection pauses, circuit breaker exceptions during reindex, and timeouts in the storefront.

Single node clusters and yellow health

Many Magento stores run one OpenSearch node. By default an index asks for one replica, and a replica can never be placed on the same node as its primary, so the cluster stays yellow. Search still works, but a yellow cluster hides real problems. On a single node I add an index template so new Magento indexes are created with zero replicas:

curl -s -X PUT 'http://opensearch:9200/_index_template/magento2' \
  -H 'Content-Type: application/json' \
  -d '{
    "index_patterns": ["magento2_*"],
    "template": { "settings": { "number_of_replicas": 0 } }
  }'

Match the pattern to your index prefix. On a real multi node cluster keep at least one replica.

Disk watermarks

When a node passes the high disk watermark, OpenSearch stops allocating shards to it, and at the flood stage it marks indexes read only. Magento then fails the reindex with an error about a blocked index. Free the space first. Then remove the block if the cluster did not lift it by itself:

curl -s -X PUT 'http://opensearch:9200/magento2_*/_settings' \
  -H 'Content-Type: application/json' \
  -d '{"index.blocks.read_only_allow_delete": null}'

Security plugin

OpenSearch ships with a security plugin that enables TLS and authentication. In production keep it on and configure the username and password in Magento. On a local Docker setup many developers disable it to keep things simple. That is fine on a laptop and never acceptable on a server that is reachable from outside.

Speeding up catalogsearch_fulltext

The full text indexer is often the slowest one. A few things make a measurable difference.

• Fewer searchable attributes. Every attribute with Use in Search set to Yes is added to the product document. Shops accumulate dozens of searchable attributes that no customer types into the search box. Review them, see product attribute best practices.
• Update by Schedule. With the indexer on schedule, product saves add rows to the changelog and cron reindexes only what changed. Full reindexes become rare. The trade offs are covered in indexer modes: save vs schedule.
• Batch sizes. Magento reads product data from MySQL and sends it to OpenSearch in batches. The sizes can be changed in env.php under the indexer batch size settings. Larger batches mean fewer round trips but more PHP memory per batch. Change them only after measuring.

'indexer' => [
    'batch_size' => [
        'catalogsearch_fulltext' => [
            'partial_reindex' => 100,
            'mysql_get' => 500,
            'elastic_save' => 500,
        ],
    ],
],

To time a full reindex on a staging copy:

time bin/magento indexer:reindex catalogsearch_fulltext

Storefront settings that affect load

Under Catalog Search in the admin there are options that add work on each search request. Search Suggestions and Search Recommendations each run extra queries. Autocomplete Limit controls how many suggestions the quick search box returns as the customer types. Minimal Query Length avoids searches for one or two characters, which return almost the whole catalog and are expensive to aggregate for layered navigation.

Layered navigation is where OpenSearch does the most work on category pages. Each filterable attribute becomes an aggregation. Having fifty filterable attributes on a category that only uses five still costs aggregation time. Mark attributes as filterable only where they are used.

Debugging search problems

Product missing from results

Work through it in order. Is the product enabled, visible in search, assigned to the website and salable or are out of stock products shown? Is the indexer valid and the changelog empty? Then check the document itself. Find the index behind the alias and search it by SKU:

curl -s 'http://opensearch:9200/magento2_product_1/_search?pretty' \
  -H 'Content-Type: application/json' \
  -d '{"query": {"match": {"sku": "ABC-123"}}}'

The number after product_ is the store ID. If the document is missing, the problem is indexing. If it is present, the problem is the query, relevance or a filter such as visibility or stock.

Errors during reindex

• Mapping conflicts. Usually an attribute whose type changed, or a custom module adding a field with the wrong type. A full reindex rebuilds the index with fresh mappings.
• Too many fields. OpenSearch limits the number of fields per index. Stores with many attributes and many store views can hit it. Reducing searchable and filterable attributes is the real fix.
• Timeouts. Raise the Magento server timeout only after you know why the cluster is slow. Most of the time it is heap pressure or disk.

Relevance tuning, synonyms and stopwords have their own article: search synonyms and relevance.

Monitoring

At minimum, alert on cluster health not green, JVM heap above about 85 percent for a sustained period, and disk above the low watermark. Also alert on Magento's own side: indexers invalid, changelog backlog growing, and cron not running. Most search outages I have looked into started with one of these going unnoticed for days.

FAQ

Can Magento 2.4.8 run without OpenSearch or Elasticsearch?

No. Since 2.4.0 a search engine is required and MySQL search was removed. Catalog listing, search and layered navigation all depend on it. Some third party modules replace it with other engines, but the core needs one.

How much memory does OpenSearch need for Magento?

It depends on catalog size and store views. A few gigabytes of heap is enough for most stores. Set Xms and Xmx to the same value, around half the machine memory, and watch heap usage during a full reindex.

Why is my OpenSearch cluster yellow?

On a single node it is almost always unassigned replica shards. Set replicas to zero for the Magento indexes with an index template. On a multi node cluster, check allocation with the cluster allocation explain API.

Do I need to reindex after changing OpenSearch settings in Magento?

After changing the host or port, no, just flush the config cache. After changing the index prefix or the engine, run a full catalogsearch_fulltext reindex so the indexes exist under the new names.

I am available for freelance Magento and Adobe Commerce work, including search setup and performance. If you need help with this, get in touch.