{"record":{"id":"ef4a85ebbac62f25","repo":"gradle/gradle","slug":"s-is-not-a-valid-gradle-version-string-example","errorCode":null,"errorMessage":"'%s' is not a valid Gradle version string (examples: '9.0.0', '9.1.0-rc-1')","messagePattern":"'(.+?)' is not a valid Gradle version string \\(examples: '9\\.0\\.0', '9\\.1\\.0-rc-1'\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"platforms/core-runtime/base-services/src/main/java/org/gradle/util/internal/DefaultGradleVersion.java","lineNumber":118,"sourceCode":"        return CURRENT;\n    }\n\n    /**\n     * Parses the given string into a GradleVersion.\n     *\n     * @throws IllegalArgumentException On unrecognized version string.\n     */\n    public static DefaultGradleVersion version(String version) throws IllegalArgumentException {\n        return new DefaultGradleVersion(version, null, null, null);\n    }\n\n    private DefaultGradleVersion(String version, @Nullable String buildTime, @Nullable String commitId, @Nullable String scriptTemplateCommitId) {\n        this.version = version;\n        this.buildTime = buildTime;\n        this.scriptTemplateCommitId = scriptTemplateCommitId;\n        Matcher matcher = VERSION_PATTERN.matcher(version);\n        if (!matcher.matches()) {\n            throw new IllegalArgumentException(format(\"'%s' is not a valid Gradle version string (examples: '9.0.0', '9.1.0-rc-1')\", version));\n        }\n\n        versionPart = matcher.group(1);\n        majorPart = Integer.parseInt(matcher.group(2), 10);\n\n        this.commitId = setOrParseCommitId(commitId, matcher);\n        this.stage = parseStage(matcher);\n        this.snapshot = parseSnapshot(matcher);\n    }\n\n    private @Nullable Long parseSnapshot(Matcher matcher) {\n        if (\"snapshot\".equals(matcher.group(5)) || isCommitVersion(matcher)) {\n            return 0L;\n        } else if (matcher.group(8) == null) {\n            return null;\n        } else if (\"SNAPSHOT\".equals(matcher.group(8))) {\n            return 0L;\n        } else {","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/gradle/gradle/blob/534f27719b66953f95cc907aae7f2c1b12f5482d/platforms/core-runtime/base-services/src/main/java/org/gradle/util/internal/DefaultGradleVersion.java#L100-L136","documentation":"DefaultGradleVersion.version(String) parses a version against a strict pattern that expects major.minor.micro plus an optional stage suffix (for example '9.0.0', '9.1.0-rc-1', and milestone/snapshot/commit-id forms). Any string that does not match the whole pattern is rejected immediately with IllegalArgumentException. The message echoes the offending string and shows two example formats.","triggerScenarios":"Calling DefaultGradleVersion.version(...) with '9' (missing minor and micro), '9.0', 'v9.0.0', '9.0.0-rc' (stage without a number), '9.0.0.1' (extra component), an empty string, or a string with leading/trailing whitespace.","commonSituations":"Build logic or plugins that parse 'gradle --version' output, wrapper distribution URLs, or GRADLE_HOME folder names; versions produced by a different convention (leading 'v', two-part versions); scripts that forget to trim tool output before parsing.","solutions":["Supply a full major.minor.micro version such as '9.0.0' or '9.1.0-rc-1'","Normalize before parsing: trim whitespace and strip a leading 'v'","Validate with a regex like ^[0-9]+\\.[0-9]+\\.[0-9]+(-.*)?$ before calling version()","Wrap the call in try/catch IllegalArgumentException and fall back to a default when the input is free-form"],"exampleFix":"// before\nDefaultGradleVersion v = DefaultGradleVersion.version(raw); // raw = \"v9.0.0\"\n\n// after\nString normalized = raw.trim().replaceFirst(\"^v\", \"\");\nDefaultGradleVersion v = DefaultGradleVersion.version(normalized); // \"9.0.0\"","handlingStrategy":"validation","validationCode":"static boolean isParsableGradleVersion(String s) {\n    return s != null && s.trim().matches(\"[0-9]+\\\\.[0-9]+\\\\.[0-9]+(-.*)?\");\n}\n\nif (!isParsableGradleVersion(raw)) {\n    throw new IllegalArgumentException(\"Bad Gradle version: \" + raw);\n}","typeGuard":null,"tryCatchPattern":"try {\n    DefaultGradleVersion.version(candidate);\n} catch (IllegalArgumentException e) {\n    // reject the input with your own message; do not retry the same string\n}","preventionTips":["Trim and strip a leading 'v' before parsing","Parse versions from structured sources (wrapper properties) instead of command output","Unit-test every version shape you expect to handle"],"tags":["gradle","version-parsing","validation","illegal-argument"],"backgroundTag":"version-string-parse-failed","analyzedSha":"534f27719b66953f95cc907aae7f2c1b12f5482d","analyzedAt":"2026-08-22T08:09:12.375Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}