Throws {@link IllegalArgumentException} if the given string could not be parsed as a\n * semantic version number or is too large to fit into a {@link Version}.\n */\n public static Version parse(String version) {\n var result = parseOrNull(version);\n if (result != null) return result;\n\n if (VERSION.matcher(version).matches()) {\n throw new IllegalArgumentException(\n String.format(\"`%s` is too large to fit into a Version.\", version));\n }\n\n throw new IllegalArgumentException(\n String.format(\"`%s` could not be parsed as a semantic version number.\", version));\n }\n\n /**\n * Parses the given string as a semantic version number.\n *\n *
Returns {@code null} if the given string could not be parsed as a semantic version number or\n * is too large to fit into a {@link Version}.\n */\n public static @Nullable Version parseOrNull(String version) {\n var matcher = VERSION.matcher(version);\n if (!matcher.matches()) return null;\n\n try {","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/Version.java#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"Passing raw user/telemetry version strings without sanity limits; malicious or test inputs with huge numbers; timestamp-like values accidentally used as version numbers.","solutions":["Validate that version components fit sane bounds before calling parse","Use parseOrNull and handle null instead of parse for untrusted input","Normalize/trim leading zeros or oversized components at the source","Catch IllegalArgumentException and surface a clear validation message"],"exampleFix":"// before\nVersion v = Version.parse(userInput); // throws on huge numbers\n// after\nVersion v = Version.parseOrNull(userInput);\nif (v == null) throw new ValidationException(\"unsupported version: \" + userInput);","handlingStrategy":"validation","validationCode":"if (!versionStr.matches(\"^\\\\d{1,9}\\\\.\\\\d{1,9}\\\\.\\\\d{1,9}([-+].*)?$\")) throw new ValidationException(\"version components too large: \" + versionStr);\n","typeGuard":"boolean isParsableVersion(String s) { return Version.parseOrNull(s) != null; }\n","tryCatchPattern":"try { v = Version.parse(input); } catch (IllegalArgumentException e) { throw new ValidationException(\"invalid version: \" + input, e); }\n","preventionTips":["Bound numeric components before parsing untrusted versions","Prefer parseOrNull for external input","Sanitize version strings from telemetry/user input","Add unit tests for oversized version components"],"tags":["pkl","versioning","parsing","validation"],"backgroundTag":"invalid-argument-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}