How to Configure Elasticsearch and OpenSearch in Magento 2

Magento 2 relies on a search engine for catalog search, layered navigation, and product sorting. Since version 2.4, Magento requires either Elasticsearch or OpenSearch as the catalog search engine. Proper configuration is essential for stable store operation, and misconfigurations are among the most frequent causes of frontend errors and degraded search quality.

Version Compatibility

Not every version of Elasticsearch or OpenSearch works correctly with every Magento release. Using an incompatible version leads to indexing failures, broken search, or missing layered navigation filters.

Elasticsearch

Magento Version	Supported ES Versions	Notes
2.4.0 – 2.4.3	7.6 – 7.9	ES 7.6 lacks case_insensitive parameter support
2.4.4 – 2.4.6	7.10 – 7.17	ES 7.10+ recommended
2.4.7+	7.17 (deprecated)	ES deprecated in favor of OpenSearch
2.4.8+	Not supported	ES removed, OpenSearch is the default

OpenSearch

Magento Version	Supported OS Versions	Notes
2.4.4+	1.x, 2.x	OpenSearch 2.x recommended
2.4.6+	2.x	Full support
2.4.7+	2.x	Preferred engine
2.4.8+	2.x, 3.4.0+	OS 3.2 has aggregation bugs -- use 3.4.0 or later

When choosing a version, avoid Elasticsearch 7.6 (missing case_insensitive parameter causes errors in some queries) and OpenSearch 3.2 (known aggregation bugs that break layered navigation counts).

Configuring the Search Engine in Magento

Navigate to Stores → Configuration → Catalog → Catalog → Catalog Search and set:

• Search Engine: Select either "Elasticsearch 7" or "OpenSearch" depending on your installed engine
• Server Hostname: Usually localhost or the container/service name
• Server Port: Default is 9200
• Index Prefix: Use a unique prefix per store instance (e.g., magento2_prod)
• Enable Auth: Set if your engine requires HTTP Basic authentication

Search Engine Type Mismatch

A common configuration error occurs when the Magento admin shows one engine type (e.g., "OpenSearch") while a different engine is actually running (e.g., Elasticsearch 7.16.3). The selected engine in Magento configuration must match the actual running engine. To verify what is running:

curl -s localhost:9200 | grep -E "distribution|version"

If the output shows "distribution" : "opensearch", select OpenSearch in Magento. If it shows an Elasticsearch version without an OpenSearch distribution field, select the corresponding Elasticsearch option.

After changing the engine configuration, run a full reindex:

php bin/magento indexer:reindex

Common Errors and Solutions

Fielddata Error on Text Attributes

Error: illegal_argument_exception: Fielddata is disabled on text fields by default

This happens when a text-type attribute is used in sorting or layered navigation. Elasticsearch does not allow fielddata on text fields by default because it consumes excessive memory.

Solution: In the Magento admin, go to Stores → Attributes → Product, open the affected attribute, and set "Use in Layered Navigation" to No. Then reindex:

php bin/magento indexer:reindex catalogsearch_fulltext

Number Format Exception on Searchable Attributes

Error: number_format_exception: For input string "..."

Numeric attributes marked as "Use in Search" = Yes can cause this error when non-numeric data exists in those fields, or when the mapping type conflicts with actual data.

Solution: Either remove the attribute from searchable attributes (set "Use in Search" = No) or ensure data consistency across all products for that attribute.

Index Name Must Be Lowercase

Starting with Magento 2.4.7-p7, Elasticsearch index names are enforced as lowercase. If your index prefix contains uppercase characters, reindexing will fail with an "Invalid Index Name Must Be Lowercase" error.

Solution: Change the index prefix in Stores → Configuration → Catalog → Catalog Search to use only lowercase characters and reindex.

Cleaning Up the search_query Table

The search_query table stores every search term submitted by visitors, including bot-generated spam queries. On busy stores, this table can grow to 600,000+ records, causing slow admin search term pages and degraded autocomplete performance.

To clean up:

-- Check table size
SELECT COUNT(*) FROM search_query;

-- Remove queries with zero results and low popularity
DELETE FROM search_query WHERE num_results = 0 AND popularity <= 1;

-- Remove very old queries
DELETE FROM search_query WHERE updated_at < DATE_SUB(NOW(), INTERVAL 6 MONTH);

After cleanup, reindex the catalog search index.

Protecting Against Bot Search Traffic

Search bots and automated scrapers can flood the search endpoint with thousands of unique queries, bloating the search_query table and putting unnecessary load on Elasticsearch.

Magento does not include built-in bot protection for the search endpoint. Protection must be implemented at the infrastructure level:

• WAF rate limiting: Set a threshold (e.g., 30 requests per minute per IP) for the catalogsearch/result URL pattern
• Referer validation: Block search requests without a valid referer header at the web server level
• CAPTCHA: Enable reCAPTCHA for the search form if your Magento version supports it

See also: Recaptcha in Magento

Migrating from Elasticsearch to OpenSearch

Since Elasticsearch is deprecated in Magento 2.4.7+ and removed in 2.4.8, migrating to OpenSearch is recommended for all stores planning an upgrade.

OpenSearch is an open-source fork of Elasticsearch 7.10.2 and is largely API-compatible. The migration steps are:

1. Install OpenSearch 2.x (or 3.4.0+ for Magento 2.4.8)
2. Stop Elasticsearch
3. In Magento admin, change Stores → Configuration → Catalog → Catalog Search → Search Engine to "OpenSearch"
4. Update the hostname and port if they differ from the ES installation
5. Run a full reindex: php bin/magento indexer:reindex
6. Verify search and layered navigation work correctly on the frontend

No data migration is needed -- Magento rebuilds all search indexes from the database during reindexing.