{"record":{"id":"ca0e3f84949da233","repo":"openzipkin/zipkin","slug":"invalid-version-number-s-for-version-distribu","errorCode":null,"errorMessage":"Invalid .version.number: %s, for .version.distribution:%s","messagePattern":"Invalid \\.version\\.number: (.+?), for \\.version\\.distribution:(.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/BaseVersion.java","lineNumber":106,"sourceCode":"        throw new IllegalArgumentException(\n          \".version.number not found in response: \" + contentString.get());\n      }\n\n      Matcher matcher = REGEX.matcher(version);\n      if (!matcher.matches()) {\n        throw new IllegalArgumentException(\"Invalid .version.number: \" + version);\n      }\n\n      try {\n        int major = Integer.parseInt(matcher.group(1));\n        int minor = Integer.parseInt(matcher.group(2));\n        if (\"opensearch\".equalsIgnoreCase(distribution)) {\n          return new OpensearchVersion(major, minor);\n        } else {\n          return new ElasticsearchVersion(major, minor);\n        }\n      } catch (NumberFormatException e) {\n        throw new IllegalArgumentException(\"Invalid .version.number: \" + version\n          + \", for .version.distribution:\" + distribution);\n      }\n    }\n  }\n}\n","sourceCodeStart":88,"sourceCodeEnd":112,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/BaseVersion.java#L88-L112","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Run curl against the storage host's GET / endpoint and inspect .version.number and .version.distribution; confirm they are plain numeric major.minor strings.","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.","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.","Set the version/distribution explicitly via configuration if your zipkin version supports it, bypassing auto-detection."],"exampleFix":"// before: cluster reports {\"version\":{\"number\":\"7.10.2+buildX\",\"distribution\":\"elasticsearch\"}}\n// BaseVersion.parseInt throws IllegalArgumentException('Invalid .version.number: 7.10.2+buildX, for .version.distribution:elasticsearch')\n\n// after: run a clean node\n// curl http://es:9200/ -> {\"version\":{\"number\":\"7.10.2\",\"distribution\":\"elasticsearch\"}}","handlingStrategy":"try-catch","validationCode":"// before connecting Zipkin, verify the cluster reports a parseable version\ntry (var client = HttpClient.newHttpClient()) {\n  var body = client.send(HttpRequest.newBuilder(URI.create(esHost + \"/\")).GET().build(),\n      HttpResponse.BodyHandlers.ofString()).body();\n  var number = new com.fasterxml.jackson.databind.ObjectMapper()\n      .readTree(body).path(\"version\").path(\"number\").asText(\"\");\n  if (!number.matches(\"\\\\d+\\\\.\\\\d+\\\\..*\")) {\n    throw new IllegalStateException(\"Cluster reports unparseable version.number: \" + number);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  storage.ensureIndexTemplatesOrFail(); // triggers version detection\n} catch (IllegalArgumentException e) {\n  // message contains the raw version string; fail startup with a clear config error\n  throw new IllegalStateException(\"Unsupported/malformed cluster version, check ES_HOSTS target: \" + e.getMessage(), e);\n}","preventionTips":["Pre-flight check GET / and eyeball .version.number/.version.distribution before wiring Zipkin to a cluster.","Prefer vanilla Elasticsearch/OpenSearch nodes over forks or API-gateways that rewrite the root response.","Pin the zipkin-server version whose supported version range matches your cluster."],"tags":["elasticsearch","opensearch","version-detection","configuration","storage"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}