openzipkin/zipkin · error · IllegalArgumentException

The distribution version is not supported: %s

Error message

The distribution version is not supported: %s

What it means

VersionSpecificTemplates.forVersion(BaseVersion) selects the DistributionSpecificTemplates implementation by instanceof: ElasticsearchVersion -> Elasticsearch templates, OpensearchVersion -> OpenSearch templates, anything else -> IllegalArgumentException. It is an internal factory guard asserting that version parsing only ever produces the two known distribution types.

Source

Thrown at zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/VersionSpecificTemplates.java:276

     * @param templatePriority index template priority
     * @return index templates
     */
    abstract IndexTemplates get(String indexPrefix, int indexReplicas, int indexShards,
      boolean searchEnabled, boolean strictTraceId, Integer templatePriority);
  }

  /**
   * Creates a new {@link DistributionSpecificTemplates} instance based on the distribution
   * @param version distribution version
   * @return {@link OpensearchSpecificTemplates} or {@link ElasticsearchSpecificTemplates} instance
   */
  static DistributionSpecificTemplates forVersion(BaseVersion version) {
    if (version instanceof ElasticsearchVersion) {
      return new ElasticsearchSpecificTemplates.DistributionTemplate((ElasticsearchVersion) version);
    } else if (version instanceof OpensearchVersion) {
      return new OpensearchSpecificTemplates.DistributionTemplate((OpensearchVersion) version);
    } else {
      throw new IllegalArgumentException("The distribution version is not supported: " + version);
    }
  }
}

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Do not introduce new BaseVersion subclasses without adding a matching branch in forVersion.
2. If you hit this in vanilla Zipkin, report a bug — it indicates a classpath mixing incompatible zipkin-storage-elasticsearch builds.
3. Align all zipkin jars to the same version so BaseVersion/VersionSpecificTemplates come from one build.

Example fix

// before (fork): class MyVersion extends BaseVersion { ... } passed to forVersion -> IAE

// after: add a branch
static DistributionSpecificTemplates forVersion(BaseVersion version) {
  if (version instanceof ElasticsearchVersion) return ...;
  if (version instanceof OpensearchVersion) return ...;
  if (version instanceof MyVersion) return new MySpecificTemplates(...);
  throw new IllegalArgumentException("The distribution version is not supported: " + version);
}

// internal invariant; if hit in vanilla builds it means mixed zipkin jar versions on the classpath
try {
  DistributionSpecificTemplates t = VersionSpecificTemplates.forVersion(version);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Classpath mixes incompatible zipkin-storage-elasticsearch builds", e);
}

When it happens

Trigger: Effectively unreachable through public configuration, because BaseVersion.parseInt only ever constructs ElasticsearchVersion or OpensearchVersion (see the source in error 80). It fires only if a custom/forked build adds a third BaseVersion subclass (or test code constructs one) and passes it into forVersion.

Common situations: Forking zipkin-storage-elasticsearch and introducing a new distribution type without extending VersionSpecificTemplates; unit tests with anonymous BaseVersion subclasses; AOT/reflection frameworks instantiating unexpected proxy classes.

Related errors

• logger == null
• no {name} property in {fileName}
• empty {name} property in {fileName}
• No valid endpoints found in ES hosts: {hosts}
• credential refresh thread didn't start

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