openzipkin/zipkin · critical · IllegalArgumentException

Invalid .version.number: %s

Error message

Invalid .version.number: %s

What it means

BaseVersion.Parser.convert() throws IllegalArgumentException('Invalid .version.number') when the version.number string does not match the '(\d+)\.(\d+).*' regex or its major/minor groups are not parseable integers. Zipkin needs a numeric major.minor to pick behavior per server version, so unrecognized formats are rejected.

Source

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

                case "number":
                  version = parser.getText();
                  break;
              }
            }
          }
        }
      } catch (RuntimeException | IOException possiblyParseException) {
        // EmptyCatch ignored
      }

      if (version == null) {
        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. Check the reported version.number via curl and use a server that reports a standard semver-like value (e.g. '7.17.9').
2. Upgrade or replace the fork/proxy that mangles version.number.
3. If running a custom build, ensure its node info exposes a numeric version.

String v = http.getJson(esUrl + "/").path("version").path("number").asText(null);
if (v == null || !v.matches("\\d+\\.\\d+.*")) throw new IllegalStateException("Unrecognized version.number '" + v + "'; use standard ES/OpenSearch");

static boolean isStandardVersionNumber(String v) { return v != null && v.matches("\\d+\\.\\d+.*"); }

catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Invalid .version.number")) failWithServerCompatibilityHint(e.getMessage()); else throw e; }

When it happens

Trigger: A server reporting version.number like 'v8.1', 'latest', '8.x', or otherwise lacking numeric major.minor components.

Common situations: Elasticsearch/OpenSearch forks, spoofed version strings behind proxies, or pre-release builds with nonstandard version metadata.

Related errors

• No content reading Elasticsearch/OpenSearch version
• .version.number not found in response: %s
• no {name} property in {fileName}
• empty {name} property in {fileName}
• No valid endpoints found in ES hosts: {hosts}

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