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 first attempts parseOrNull; if that fails but the string still matches the VERSION regex shape, the numeric components exceed the ranges representable in Pkl's packed Version type. It throws IllegalArgumentException saying the version is "too large to fit into a Version".

Source

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

    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. Use a version string whose major/minor/patch fit within supported ranges (small non-negative integers).
2. Pre-validate components with a regex and bound check before calling Version.parse, or use Version.parseOrNull and handle null.
3. Catch IllegalArgumentException and surface a user-friendly message asking for a conventional semver like 1.2.3.

Example fix

// before
Version v = Version.parse("999999999999.1.0"); // throws
// after
Version v = Version.parse("9999.1.0"); // within representable range

boolean isPlausibleVersion(String s) {
  var m = Pattern.compile("^(\\d+)\\.(\\d+)\\.(\\d+)$").matcher(s);
  return m.matches()
      && m.group(1).length() <= 4 && m.group(2).length() <= 4 && m.group(3).length() <= 4;
}

Version safeParse(String s) { var v = Version.parseOrNull(s); if (v == null) { log.warn("unusable version: {}", s); } return v; }

try {
  return Version.parse(input);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Version too large or malformed: " + input, e);
}

When it happens

Trigger: Version.parse("1.999999999999.0") or similar — a syntactically valid semver string whose major/minor/patch components overflow the internal integer encoding.

Common situations: Parsing untrusted/user-supplied version strings; versions from external registries that use huge build counters; tests with sentinel versions like 99999.0.0.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• `%s` could not be parsed as a semantic version number.
• `%s` is too large to fit into a Version.
• Pkl module `%s` does not state which Pkl version it requires
• Pkl version `%s` requested by module `%s` is not supported.
• Failed to parse Pkl module URI: ${notation}

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