Upgrade to a Quarterly Release Fails with "Elasticsearch sidecar could not be started" Error

Issue

When upgrading from Liferay DXP 7.2 to a Liferay DXP 7.4 Quarterly Release, the server startup fails. The logs show errors related to Elasticsearch, such as:

2025-07-10 09:29:51.414 ERROR [SystemExecutorServiceUtil-2][ElasticsearchConnectionManager:80] Elasticsearch sidecar could not be started. Search will be unavailable. Manual installation of Elasticsearch and activation of remote mode is recommended.
java.lang.RuntimeException: java.net.ConnectException: Connection timed out

Or:

2025-07-08 13:14:50.724 ERROR [main][SidecarManager:84] bundle com.liferay.portal.search.elasticsearch7.impl:5.0.68 (665)[com.liferay.portal.search.elasticsearch7.internal.sidecar.SidecarManager(1754)] : 
The activate method has thrown an exception java.lang.RuntimeException: javax.net.ssl.SSLException: Connection reset
at com.liferay.portal.search.elasticsearch7.internal.sidecar.ElasticsearchInstaller.install(ElasticsearchInstaller.java:62)

 

This issue occurs if the Elasticsearch configuration was saved in the Liferay DXP 7.2 environment. During the upgrade, this configuration is carried over, but it points to the old directory name for the embedded Elasticsearch sidecar (elasticsearch7). In Liferay DXP 7.4 Quarterly Releases, the correct directory name is elasticsearch-sidecar. 

This error can be thrown when the machine where Liferay is installed doesn't have connection to internet.

Environment

• Upgrading from Liferay DXP 7.2
• Upgrading to Liferay DXP 7.4 Quarterly Releases

Resolution

To resolve this, the Elasticsearch configuration must be updated to point to the correct sidecar home directory. There are three options to achieve this:

Option 1: Reset to Default Values

1. Navigate to Control Panel → Configuration → System Settings.
2. Go to the Search category and click on Elasticsearch 7.
3. At the top of the configuration page, click the three-dot icon and select Reset Default Values.
4. Save the configuration. This will update the Sidecar Home path to the correct default value, elasticsearch-sidecar.
5. Restart the server

Option 2: Rename the Directory

In the Liferay DXP 7.4 home directory, rename the elasticsearch-sidecar folder to elasticsearch7. This allows the old configuration path to find the directory.

Option 3: Use a Configuration File

Force the correct configuration by placing a .config file in the [LIFERAY_HOME]/osgi/configs/ directory.

1. Create a file named com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config.
2. Add the following content to the file. This ensures the sidecarHome property is set to the correct path for Quarterly Releases.

additionalConfigurations=""
additionalIndexConfigurations=""
additionalTypeMappings=""
authenticationEnabled=B"false"
bootstrapMlockAll=B"false"
clusterName="LiferayElasticsearchCluster"
discoveryZenPingUnicastHostsPort="9300-9400"
embeddedHttpPort=I"9201"
httpCORSAllowOrigin="/https?:\\/\\/localhost(:[0-9]+)?/"
httpCORSConfigurations=""
httpCORSEnabled=B"true"
httpSSLEnabled=B"false"
indexNamePrefix="liferay-"
indexNumberOfReplicas=""
indexNumberOfShards=""
logExceptionsOnly=B"true"
minimumRequiredNodeVersion="0.0.0"
networkBindHost=""
networkHost=""
networkHostAddresses=[ \
  "http://localhost:9200", \
  ]
networkPublishHost=""
nodeName=""
operationMode="EMBEDDED"
overrideTypeMappings=""
productionModeEnabled=B"false"
proxyHost=""
proxyPort=I"0"
proxyUserName=""
remoteClusterConnectionId=""
restClientLoggerLevel="ERROR"
sidecarDebug=B"false"
sidecarDebugSettings="-agentlib:jdwp\=transport\=dt_socket,address\=8001,server\=y,suspend\=y,quiet\=y"
sidecarHeartbeatInterval=L"10000"
sidecarHome="elasticsearch-sidecar"
sidecarHttpPort=""
sidecarJVMOptions=[ \
  "-Xms1g", \
  "-Xmx1g", \
  "-XX:+AlwaysPreTouch", \
  ]
sidecarShutdownTimeout=L"10000"
trackTotalHits=B"true"
transportTcpPort=""
truststorePath="/path/to/localhost.p12"
truststoreType="pkcs12"
username="elastic"

After applying one of these solutions, restart the server.