openzipkin/zipkin · error · IllegalArgumentException

Invalid .version.number: %s, for .version.distribution:%s

Error message

Invalid .version.number: %s, for .version.distribution:%s

What it means

BaseVersion parses the version string reported by the Elasticsearch/OpenSearch cluster (the '.version.number' field of the GET / response). After the overall pattern matches, Integer.parseInt is applied to the captured major/minor groups; if either group is not a parseable integer, NumberFormatException is caught and rethrown as IllegalArgumentException naming the version and distribution. It means the cluster reported a version string this build cannot turn into a numeric major.minor.

Source

Thrown at zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/BaseVersion.java:106

        throw new IllegalArgumentException(
          ".version.number not found in response: " + contentString.get());
      }

      Matcher matcher = REGEX.matcher(version);
      if (!matcher.matches()) {
        throw new IllegalArgumentException("Invalid .version.number: " + version);
      }

      try {
        int major = Integer.parseInt(matcher.group(1));
        int minor = Integer.parseInt(matcher.group(2));
        if ("opensearch".equalsIgnoreCase(distribution)) {
          return new OpensearchVersion(major, minor);
        } else {
          return new ElasticsearchVersion(major, minor);
        }
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Invalid .version.number: " + version
          + ", for .version.distribution:" + distribution);
      }
    }
  }
}

View on GitHub (pinned to 878ce2a1fa)

Solutions

  1. Run curl against the storage host's GET / endpoint and inspect .version.number and .version.distribution; confirm they are plain numeric major.minor strings.
  2. Point the storage at a vanilla supported Elasticsearch (5-9.x) or OpenSearch (1-3.x) node instead of a fork/proxy that rewrites the version string.
  3. If a fork is required, upgrade zipkin-server/zipkin-storage-elasticsearch to a release whose BaseVersion regex handles that version format, or patch the parser to strip non-numeric suffixes before Integer.parseInt.
  4. Set the version/distribution explicitly via configuration if your zipkin version supports it, bypassing auto-detection.

Example fix

// before: cluster reports {"version":{"number":"7.10.2+buildX","distribution":"elasticsearch"}}
// BaseVersion.parseInt throws IllegalArgumentException('Invalid .version.number: 7.10.2+buildX, for .version.distribution:elasticsearch')

// after: run a clean node
// curl http://es:9200/ -> {"version":{"number":"7.10.2","distribution":"elasticsearch"}}
Defensive patterns

Strategy: try-catch

Validate before calling

// before connecting Zipkin, verify the cluster reports a parseable version
try (var client = HttpClient.newHttpClient()) {
  var body = client.send(HttpRequest.newBuilder(URI.create(esHost + "/")).GET().build(),
      HttpResponse.BodyHandlers.ofString()).body();
  var number = new com.fasterxml.jackson.databind.ObjectMapper()
      .readTree(body).path("version").path("number").asText("");
  if (!number.matches("\\d+\\.\\d+\\..*")) {
    throw new IllegalStateException("Cluster reports unparseable version.number: " + number);
  }
}

Try / catch

try {
  storage.ensureIndexTemplatesOrFail(); // triggers version detection
} catch (IllegalArgumentException e) {
  // message contains the raw version string; fail startup with a clear config error
  throw new IllegalStateException("Unsupported/malformed cluster version, check ES_HOSTS target: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: Any code path that resolves the server version, e.g. ElasticsearchStorage.version() during first use, ensureIndexTemplatesOrFail(), or a health check (CheckResult) against a cluster whose GET / response has a .version.number whose captured groups contain non-digits (e.g. '7.10.2+foo', '1.0.0-SNAPSHOT' style shapes, or a versioned proxy greeting that still matches the regex loosely).

Common situations: Running a fork or unusual build of Elasticsearch/OpenSearch (vendor suffixes, snapshot identifiers); pointing Zipkin at a proxy or a non-Elasticsearch service whose root response mimics the expected shape; version strings changed by newer distributions.

Related errors

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