OpenSearch vs Elasticsearch for Magento 2: Migration Guide and Common Errors

Search engine migrations aren't something Magento stores do often, which is exactly why they're so easy to get wrong the one time it matters. Here's what actually changes and what tends to break.

Why This Migration Is Happening Now

Elastic's licensing changes pushed much of the open-source ecosystem — including Magento/Adobe Commerce — toward OpenSearch as the community-driven, Apache-2.0-licensed fork. Recent Magento versions support OpenSearch as a first-class search engine option alongside Elasticsearch, and it's increasingly the recommended default for new installs.

Check What Your Version Actually Supports

Before doing anything, confirm your current search engine configuration:

bin/magento config:show catalog/search/engine

Not every Magento version supports every OpenSearch version — check the official compatibility matrix for your exact Magento version before assuming "latest OpenSearch" is a safe choice. Mismatches here are the single biggest source of migration headaches.

Switching the Engine Configuration

bin/magento config:set catalog/search/engine opensearch
bin/magento config:set catalog/search/opensearch_server_hostname <host>
bin/magento config:set catalog/search/opensearch_server_port 9200
bin/magento config:set catalog/search/opensearch_index_prefix magento2

You Must Fully Reindex Afterward

Switching the engine config doesn't migrate existing index data — Elasticsearch and OpenSearch don't share index state, even when running on the same infrastructure. A full reindex of the search index is mandatory after switching:

bin/magento indexer:reindex catalogsearch_fulltext

Skipping this step is the most common reason a migration "works" (no errors) but search results are empty or stale — Magento is pointed at an engine with no index built yet.

Common Error: Connection Refused

curl -X GET "http://localhost:9200"

If this fails, Magento's error will look like a generic search exception with no obvious engine-specific detail. Check that the service is actually running on the host/port you configured, and that nothing (a firewall, a security group, a Docker network) is blocking the connection between the app and the search cluster.

Common Error: Mapping/Version Incompatibility

If reindexing throws errors referencing field mappings or unsupported cluster features, it usually means the OpenSearch version you're running doesn't match what your Magento version's search adapter expects. This is where checking the compatibility matrix before migrating pays off — after the fact, the fix is almost always "run a supported version," not a config tweak.

Verify the Cluster Is Actually Healthy

Don't stop at "connection works" — check cluster health specifically:

curl -X GET "http://localhost:9200/_cluster/health?pretty"

A yellow or red status can still let Magento connect and even reindex, while producing inconsistent or missing results under real traffic.

Test Search Behavior, Not Just That It Runs Without Errors

After migrating, manually verify:

• Storefront search returns expected results for a handful of known queries.
• Layered navigation facets (price, custom attributes) populate correctly.
• Search-as-you-type / autocomplete (if enabled) still works.

A clean reindex log doesn't guarantee correct search behavior — mapping differences between engines can silently change how certain attribute types are indexed.

Rollback Plan

Keep your old engine's configuration values noted before switching, and don't decommission the old search cluster until you've verified the new one in production traffic for at least a few days. Switching back is just re-running the config:set commands above with the previous engine and host, followed by another full reindex.