openzipkin/zipkin · error · IllegalArgumentException

OpenSearch versions 1-3.x are supported, was: %s

Error message

OpenSearch versions 1-3.x are supported, was: %s

What it means

OpensearchSpecificTemplates.get(version) builds index templates for OpenSearch and only supports 1.x through 3.x: any version below 1.0.0 or 4.0.0 and above is rejected with IllegalArgumentException. The version compared comes from cluster auto-detection (or explicit configuration) with distribution opensearch.

Source

Thrown at zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/OpensearchSpecificTemplates.java:71

      + "-*"
      + "\"";
  }
  
  static char indexTypeDelimiter(OpensearchVersion version) {
    return '-';
  }
  
  @Override boolean useComposableTemplate(OpensearchVersion version) {
    return (templatePriority != null);
  }
  
  @Override String maybeWrap(String type, OpensearchVersion version, String json) {
    return json;
  }

  @Override IndexTemplates get(OpensearchVersion version) {
    if (version.compareTo(V1_0) < 0 || version.compareTo(V4_0) >= 0) {
      throw new IllegalArgumentException(
        "OpenSearch versions 1-3.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 that supports your OpenSearch version.
2. Or keep the cluster on OpenSearch 1-3.x.
3. Remove any explicit ES_VERSION override so auto-detection picks the right value, and confirm with curl GET / what the cluster reports.
4. If you must run 4.x now, patch OpensearchSpecificTemplates bounds and test template installation manually (PUT _index_template) before relying on it.

Example fix

# before
STORAGE_TYPE=elasticsearch OPENSEARCH=true ES_HOSTS=http://os4:9200
# cluster reports {"version":{"number":"4.0.0","distribution":"opensearch"}}
# -> IllegalArgumentException: OpenSearch versions 1-3.x are supported, was: 4.0.0

# after: use a zipkin build with OpenSearch 4 support, or pin cluster to 3.x

int major = Integer.parseInt(opensearchVersionNumber.split("\\.")[0]);
if (major < 1 || major > 3) {
  throw new IllegalStateException("Upgrade zipkin-server: this build supports OpenSearch 1-3.x, cluster is "
      + opensearchVersionNumber);
}

try {
  storage.ensureIndexTemplatesOrFail();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("OpenSearch versions 1-3.x are supported")) {
    // pin cluster to 3.x or upgrade zipkin — surface as deployment config error
  }
  throw e;
}

When it happens

Trigger: Zipkin connects with distribution=opensearch to an OpenSearch 4.x+ node (or a fork reporting version >= 4), or the version string was parsed into an out-of-range OpensearchVersion; ensureIndexTemplatesOrFail() then reaches this guard and throws.

Common situations: Upgrading the OpenSearch cluster ahead of the bundled Zipkin build; serverless offerings that report different version numbers; misconfigured ES_VERSION forcing an out-of-range value.

Related errors

• Elasticsearch versions 5-9.x are supported, was: %s
• Invalid .version.number: %s, for .version.distribution:%s
• storage == null
• No content reading Elasticsearch/OpenSearch version
• keys == null

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