apple/pkl · error · IllegalArgumentException

`%s` is too large to fit into a Version.

Error message

`%s` is too large to fit into a Version.

What it means

Version.parse could not parse the string (parseOrNull returned null) and the string DOES match the VERSION regex, meaning it is a syntactically valid semantic version whose numeric components exceed the limits storable in the Version class (numbers too large for the packed representation). A distinct IllegalArgumentException is thrown for this case rather than the generic parse failure.

Source

Thrown at pkl-executor/src/main/java/org/pkl/executor/Version.java:85

    this.major = major;
    this.minor = minor;
    this.patch = patch;
    this.preRelease = preRelease;
    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 {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Validate that version components fit sane bounds before calling parse
2. Use parseOrNull and handle null instead of parse for untrusted input
3. Normalize/trim leading zeros or oversized components at the source
4. Catch IllegalArgumentException and surface a clear validation message

Example fix

// before
Version v = Version.parse(userInput); // throws on huge numbers
// after
Version v = Version.parseOrNull(userInput);
if (v == null) throw new ValidationException("unsupported version: " + userInput);

if (!versionStr.matches("^\\d{1,9}\\.\\d{1,9}\\.\\d{1,9}([-+].*)?$")) throw new ValidationException("version components too large: " + versionStr);

boolean isParsableVersion(String s) { return Version.parseOrNull(s) != null; }

try { v = Version.parse(input); } catch (IllegalArgumentException e) { throw new ValidationException("invalid version: " + input, e); }

When it happens

Trigger: Calling Version.parse with a version whose major/minor/patch numbers are astronomically large (e.g. "999999999999.1.0") — regex-valid but overflowing the internal storage.

Common situations: Passing raw user/telemetry version strings without sanity limits; malicious or test inputs with huge numbers; timestamp-like values accidentally used as version numbers.

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` could not be parsed as a semantic version number.
• expectedNonEmptyCollection
• expectedSingleElementCollection
• invalidRegexSyntax

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