apache/beam · error · IllegalArgumentException

Expected the version string to start with

Error message

Expected the version string to start with `<major>.<minor>` but received 

What it means

compareVersions parses version strings via getVersionFromStr, which requires at least a `<major>.<minor>` form. A string with fewer than two dot-separated parts (e.g. "7" or "") cannot be compared and causes an IllegalArgumentException.

Solutions

1. Pass a full version string with at least major.minor, e.g. "2.54.0"
2. Normalize the version string before comparison (append missing ".0" parts)
3. Guard the input with a regex check like ^\d+\.\d+ before calling compareVersions

Example fix

// before
TransformUpgrader.compareVersions("8", "2.54.0") >= 0;
// after
TransformUpgrader.compareVersions("8.0.0", "2.54.0") >= 0;

import java.util.regex.Pattern;
private static final Pattern VERSION = Pattern.compile("^\\d+\\.\\d+");
if (version == null || !VERSION.matcher(version).find()) {
  throw new IllegalArgumentException("Version must be <major>.<minor>[.<patch>]: " + version);
}

try {
  TransformUpgrader.compareVersions(a, b);
} catch (IllegalArgumentException e) {
  // fallback: pad version e.g. a + ".0.0" and retry
}

When it happens

Trigger: Calling compareVersions (e.g. for transform service version checks via TransformUpgrader) with a version string like "8" or "" instead of "8.1.0".

Common situations: Environment variables or service responses reporting only a major version; typos in configured versions; build metadata stripped of minor/patch parts.

Related errors

• A list of URNs for overriding transforms was provided but…
• A cannot be expanded
• A transform cannot be initiated using the provided config…
• AVRO schema doesn't match row schema. Row schema
• BigQuery data contained value

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/d24e44b3917feabd. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/TransformUpgrader.java:490

      return in.readObject();
    } catch (InvalidClassException e) {
      LOG.info(
          "An object cannot be re-generated from the provided byte array. Caller may use the "
              + "default value for the parameter when upgrading. Underlying error: {}",
          e.toString());
      throw e;
    } catch (Exception e) {
      throw new RuntimeException(e);
    }
  }

  @SuppressWarnings({
    "nullness" // TODO(https://github.com/apache/beam/issues/20497)
  })
  private static Version getVersionFromStr(String version) {
    String[] versionParts = Splitter.onPattern("\\.").splitToList(version).toArray(new String[0]);
    if (versionParts.length < 2) {
      throw new IllegalArgumentException(
          "Expected the version string to start with `<major>.<minor>` "
              + "but received "
              + version);
    }

    // Concatenating patch and suffix to determine the correct patch version.
    String patchAndSuffix =
        versionParts.length == 2
            ? ""
            : String.join(".", Arrays.copyOfRange(versionParts, 2, versionParts.length));
    StringBuilder patchVersionBuilder = new StringBuilder();
    for (int i = 0; i < patchAndSuffix.length(); i++) {
      if (Character.isDigit(patchAndSuffix.charAt(i))) {
        patchVersionBuilder.append(patchAndSuffix.charAt(i));
      } else {
        break;
      }
    }

View on GitHub (pinned to 12126d8942)