openzipkin/zipkin · error · IllegalArgumentException

Elasticsearch versions 5-9.x are supported, was: %s

Error message

Elasticsearch versions 5-9.x are supported, was: %s

What it means

ElasticsearchSpecificTemplates.get(version) builds the index templates (span, dependency, autocomplete) and only supports Elasticsearch 5.x through 9.x: versions below 5.0.0 or 10.0.0 and above are rejected with IllegalArgumentException. The version compared is the one detected from the cluster, so this fires when the connected cluster identifies itself as an out-of-range Elasticsearch.

Source

Thrown at zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/ElasticsearchSpecificTemplates.java:96

   *
   * <p>Starting in Elasticsearch 7.x, colons are no longer allowed in index names. This logic will
   * make sure the pattern in our index template doesn't use them either.
   *
   * <p>See https://github.com/openzipkin/zipkin/issues/2219
   */
  static char indexTypeDelimiter(ElasticsearchVersion version) {
    return version.compareTo(V7_0) < 0 ? ':' : '-';
  }

  @Override String maybeWrap(String type, ElasticsearchVersion version, String json) {
    // ES 7.x defaults include_type_name to false https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-7.0.html#_literal_include_type_name_literal_now_defaults_to_literal_false_literal
    if (version.compareTo(V7_0) >= 0) return json;
    return "    \"" + type + "\": {\n  " + json.replace("\n", "\n  ") + "  }\n";
  }

  @Override IndexTemplates get(ElasticsearchVersion version) {
    if (version.compareTo(V5_0) < 0 || version.compareTo(V10_0) >= 0) {
      throw new IllegalArgumentException(
        "Elasticsearch versions 5-9.x are supported, was: " + version);
    }
    return IndexTemplates.newBuilder()
      .version(version)
      .indexTypeDelimiter(indexTypeDelimiter(version))
      .span(spanIndexTemplate(version))
      .dependency(dependencyTemplate(version))
      .autocomplete(autocompleteTemplate(version))
      .build();
  }
}

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Upgrade zipkin-server / zipkin-storage-elasticsearch to a release matching your cluster version (each release states its supported ES range).
2. Or pin the cluster to a supported Elasticsearch 5-9.x version.
3. If the target is actually OpenSearch, configure STORAGE_TYPE=elasticsearch with ES_VERSION/DISTRIBUTION set to opensearch (or use the opensearch storage mode) so OpensearchSpecificTemplates are used.
4. Verify with curl GET / what number+distribution the cluster reports and align configuration.

Example fix

# before: zipkin-server 2.x pointed at OpenSearch 2.x detected as elasticsearch
STORAGE_TYPE=elasticsearch ES_HOSTS=http://opensearch:9200
# -> IllegalArgumentException: Elasticsearch versions 5-9.x are supported, was: 2.x

# after
STORAGE_TYPE=elasticsearch ES_HOSTS=http://opensearch:9200 ES_VERSION=2.14 OPENSEARCH=true
# (or upgrade zipkin-server which auto-detects distribution)

// before wiring storage, confirm the cluster version is in the supported ES range
var m = java.util.regex.Pattern.compile("(\\d+)\\.(\\d+)\\..*").matcher(esVersionNumber);
if (!m.matches() || Integer.parseInt(m.group(1)) < 5 || Integer.parseInt(m.group(1)) > 9) {
  throw new IllegalStateException("Use a zipkin build matching ES " + esVersionNumber
      + " or pin the cluster to ES 5-9.x");
}

try {
  ElasticsearchStorage.newBuilder(...).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("versions 5-9.x are supported")) {
    // version/distribution mismatch: surface a config error, hint at distribution=opensearch or upgrade
  }
  throw e;
}

When it happens

Trigger: Zipkin storage connects to Elasticsearch 2.x/1.x or a future 10.x+ node; ensureIndexTemplatesOrFail() then calls VersionSpecificTemplates.forVersion(...).get(version) and this guard throws. Also happens when an OpenSearch cluster is misidentified as Elasticsearch because .version.distribution was absent (older OpenSearch builds) and the code fell into the Elasticsearch branch.

Common situations: Upgrading the Elasticsearch cluster beyond what the bundled Zipkin build supports; running old ES 2.x in legacy environments; connecting to OpenSearch with an old zipkin-server that does not set distribution=opensearch.

Related errors

• OpenSearch versions 1-3.x are supported, was: %s
• Invalid .version.number: %s, for .version.distribution:%s
• storage == null
• no {name} property in {fileName}
• empty {name} property in {fileName}

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/9481c6b8e32c7bcc. Report an issue: GitHub.