KB-2340 Data server fails to start because localhost lookup fails

Symptoms

When attempting to start the Appian Data Server (ADS), the startup fails due to the following errors in watchdog.log:

com.appian.data.server.UnrecoverableError: Lost WebSocket connection with localhost:5410. The target Go process exited abnormally. Check for earlier errors (e.g. Go startup errors).

The following error may also appear:

dial tcp: lookup localhost: Try again

Cause

ADS is unable to establish a connection to the necessary ports because "localhost" is not resolvable to the IP address of the server (ex: 127.0.0.1), which causes the lookup and connection to fail.

Action

Check the hosts file of the server to ensure that there is an entry for the FQDN of the Appian instance that resolves to the IP address of the server (the same FQDN used in appian-topology.xml). If Appian is being hosted locally on the server, "localhost" can be used, but it must explicitly resolve to 127.0.0.1 in the host file.

Note that Appian recommends using FQDNs instead of "localhost" in appian-topology.xml and the hosts file to mitigate confusion and prevent errors of this nature. Additionally, please make sure that the content of appian-topology.xml is exactly the same in <APPIAN_HOME>/conf/, <APPIAN_HOME>/data-server/conf/, <APPIAN_HOME>/search-server/conf/ on each server and between all three nodes in the case of an HA installation.

Affected Versions

This article applies to all non-containerized self-managed versions of Appian.

Last Reviewed: June 2025

Related
Recommended