apache/beam · error · IllegalArgumentException

Cannot get Elasticsearch version

Error message

Cannot get Elasticsearch version

What it means

getBackendVersion(RestClient) queries the cluster's root endpoint to read version.number and map it to an internal backend version constant. If the HTTP request itself fails (connection error, timeout, non-parseable response producing IOException), the IOException is wrapped into an IllegalArgumentException with this message. It means the library could not talk to or understand the Elasticsearch cluster.

Source

Thrown at sdks/java/io/elasticsearch/src/main/java/org/apache/beam/sdk/io/elasticsearch/ElasticsearchIO.java:3023

  static int getBackendVersion(RestClient restClient) {
    try {
      Request request = new Request("GET", "");
      Response response = restClient.performRequest(request);
      JsonNode jsonNode = parseResponse(response.getEntity());
      int backendVersion =
          Integer.parseInt(jsonNode.path("version").path("number").asText().substring(0, 1));
      checkArgument(
          VALID_CLUSTER_VERSIONS.contains(backendVersion),
          "The Elasticsearch version to connect to is %s.x. "
              + "This version of the ElasticsearchIO is only compatible with "
              + "Elasticsearch "
              + VALID_CLUSTER_VERSIONS,
          backendVersion);
      maybeLogVersionDeprecationWarning(backendVersion);
      return backendVersion;

    } catch (IOException e) {
      throw new IllegalArgumentException("Cannot get Elasticsearch version", e);
    }
  }

  static int getBackendVersion(ConnectionConfiguration connectionConfiguration) {
    try (RestClient restClient = connectionConfiguration.createClient()) {
      return getBackendVersion(restClient);
    } catch (IOException e) {
      throw new IllegalArgumentException("Cannot get Elasticsearch version", e);
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the wrapped IOException cause for the network/connection error
2. Verify ConnectionConfiguration host, port, scheme (http/https) and credentials
3. Test connectivity: `curl -u user:pass https://es-host:9200/` from the worker environment
4. Confirm the response's version.number is a supported version (VALID_CLUSTER_VERSIONS)
5. Ensure no proxy/load balancer is returning a non-ES response body

Example fix

// before
ConnectionConfiguration.create("localhost", 9200) // unreachable from worker
// after
ConnectionConfiguration.create("elasticsearch.es.svc.cluster.local", 9200)

try (RestClient c = connectionConfiguration.createClient()) {
  Response r = c.performRequest(new Request("GET", "/"));
  if (r.getStatusLine().getStatusCode() != 200)
    throw new IllegalStateException("ES root returned " + r.getStatusLine());
}

try {
  pipeline.run();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Cannot get Elasticsearch version"))
    LOG.error("ES unreachable during validation: {}", e.getCause());
  throw e;
}

When it happens

Trigger: ElasticsearchIO.read()/write() pipeline validation calling static getBackendVersion when the RestClient request fails: wrong host/port, TLS failure, network unreachable, or malformed version response.

Common situations: Typo in ES address; cluster not reachable from the Beam worker (VPC/firewall); cluster returns unexpected JSON because a proxy intercepts; unsupported/newer ES version returning an unparsable body.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• <errorMessages.toString()>
• Error writing to ES after %d attempt(s). No more attempts al
• Illegal access to pipeline after visitor traversal was compl
• Pipeline update will not be possible because the following t
• Unrecognized value for stable unique names:

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/987dfe1e1d4b1c05. Report an issue: GitHub.