apple/pkl · error · IllegalArgumentException

`%s` could not be parsed as a semantic version number.

Error message

`%s` could not be parsed as a semantic version number.

What it means

Version.parse throws this IllegalArgumentException when the input neither parses as a Version nor even matches the VERSION regex, i.e. it is not a well-formed semantic version string at all. The fallback branch after the 'too large' check produces this message.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/Version.java:88

    this.build = build;
  }

  /**
   * Parses the given string as a semantic version number.
   *
   * <p>Throws {@link IllegalArgumentException} if the given string could not be parsed as a
   * semantic version number or is too large to fit into a {@link Version}.
   */
  public static Version parse(String version) {
    var result = parseOrNull(version);
    if (result != null) return result;

    if (VERSION.matcher(version).matches()) {
      throw new IllegalArgumentException(
          String.format("`%s` is too large to fit into a Version.", version));
    }

    throw new IllegalArgumentException(
        String.format("`%s` could not be parsed as a semantic version number.", version));
  }

  /**
   * Parses the given string as a semantic version number.
   *
   * <p>Returns {@code null} if the given string could not be parsed as a semantic version number or
   * is too large to fit into a {@link Version}.
   */
  public static @Nullable Version parseOrNull(String version) {
    var matcher = VERSION.matcher(version);
    if (!matcher.matches()) return null;

    try {
      return new Version(
          Integer.parseInt(matcher.group(1)),
          Integer.parseInt(matcher.group(2)),
          Integer.parseInt(matcher.group(3)),

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Pass a full semantic version string: MAJOR.MINOR.PATCH (e.g. "1.2.3").
2. Strip prefixes like "v" and trim whitespace before parsing.
3. Use Version.parseOrNull and branch on null to handle invalid input gracefully instead of throwing.

Example fix

// before
Version v = Version.parse("v1.2"); // throws
// after
Version v = Version.parse("1.2.0");

Pattern SEMVER = Pattern.compile("^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$");
if (!SEMVER.matcher(input).matches()) {
  throw new IllegalArgumentException("expected MAJOR.MINOR.PATCH, got: " + input);
}

Version safeParse(String s) { var v = Version.parseOrNull(s); return v; /* null when malformed */ }

try {
  return Version.parse(input);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("`" + input + "` is not a valid semver (expected e.g. 1.2.3)", e);
}

When it happens

Trigger: Version.parse with strings like "abc", "1.2", "v1.2.3", "1.2.3-beta.1+meta" if unsupported, or empty/whitespace input that fails the semver pattern.

Common situations: Reading versions from CLI args, env vars, or config files with typos or a leading 'v'; legacy version strings like "1.2"; locale-formatted versions like "1,2,3".

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• `%s` is too large to fit into a Version.
• `%s` is too large to fit into a Version.
• object
• string
• invalidPackageUriChecksum

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/376b6c223cf473b4. Report an issue: GitHub.