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 in pkl-executor validates that an input string is a semantic version number using a VERSION regex. When the string does not match (and is not merely too large to fit), it throws IllegalArgumentException stating the value could not be parsed as a semantic version. The library throws this to reject malformed version strings early instead of failing later with confusing errors.

Source

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

    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

Fix the version string to a full semver form MAJOR.MINOR.PATCH with optional -prerelease/+build, e.g. "1.2.3".
Print/inspect the offending string; strip whitespace, a leading "v", or quotes before parsing.
If the value comes from config/env, add a default or fallback constant like "0.0.0" when unset.
If you only need comparison, parse with a lenient parser first and normalize the input before calling Version.parse.

Example fix

// before
Version.parse(System.getenv("PKL_VERSION")); // "" -> throws
// after
String v = System.getenv("PKL_VERSION");
Version.parse(v == null || v.isBlank() ? "0.27.1" : v.trim().replaceFirst("^v", ""));

Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern SEMVER = Pattern.compile("^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$");
if (v == null || !SEMVER.matcher(v.trim().replaceFirst("^v","")).matches()) throw new IllegalArgumentException("Not a semver: " + v);

Type guard

static boolean isSemVer(String s) { return s != null && Pattern.compile("^\\d+\\.\\d+\\.\\d+([-.][0-9A-Za-z.-]+)*$", 0).matcher(s.trim()).matches(); }

Try / catch

try { Version.parse(v); } catch (IllegalArgumentException e) { log.error("Bad version '{}': {}", v, e.getMessage()); throw new ConfigException("pkl version must be semver", e); }

Prevention

Store versions as semver constants in code, not free-form config
Normalize input: trim, strip leading 'v', before parsing
Add a startup validation step that parses all configured versions
Use java.util.regex to pre-validate user-supplied versions

When it happens

Trigger: Calling Version.parse(String) with a string that fails the VERSION regex: missing components (e.g. "1.2"), non-numeric parts, illegal pre-release/build metadata, or entirely non-version text like "latest" or a path.

Common situations: Hardcoded version constants with typos; interpolating an env var or property that is unset or holds a placeholder; passing a version range like "1.x" or ">=1.0.0" where an exact version is expected; copying versions with stray whitespace or a leading 'v'.

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

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