spring-projects/spring-boot · error · IllegalArgumentException

'value' must contain a well formed version number [{}]

Error message

'value' must contain a well formed version number [{}]

What it means

ApiVersion.parse parses a 'major.minor' version string. First it asserts the regex PATTERN matches, then parses both captured groups as integers. NumberFormatException (e.g. integer overflow on extremely large numbers) is wrapped as IllegalArgumentException. Note the message in the throw is a plain string whereas a sibling Assert call uses %s formatting -- the two are differentiated by whether the regex matched.

Source

Thrown at buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/ApiVersion.java:137

	/**
	 * Factory method to parse a string into an {@link ApiVersion} instance.
	 * @param value the value to parse.
	 * @return the corresponding {@link ApiVersion}
	 * @throws IllegalArgumentException if the value could not be parsed
	 */
	public static ApiVersion parse(String value) {
		Assert.hasText(value, "'value' must not be empty");
		Matcher matcher = PATTERN.matcher(value);
		Assert.isTrue(matcher.matches(),
				() -> "'value' [%s] must contain a well formed version number".formatted(value));
		try {
			int major = Integer.parseInt(matcher.group(1));
			int minor = Integer.parseInt(matcher.group(2));
			return new ApiVersion(major, minor);
		}
		catch (NumberFormatException ex) {
			throw new IllegalArgumentException("'value' must contain a well formed version number [" + value + "]", ex);
		}
	}

	public static ApiVersion of(int major, int minor) {
		return new ApiVersion(major, minor);
	}

	@Override
	public int compareTo(ApiVersion other) {
		return COMPARATOR.compare(this, other);
	}

}

View on GitHub (pinned to 270dfe353f)

Solutions

1. Validate the version string format and range before calling parse
2. Catch IllegalArgumentException and fall back to a known-good default version
3. Sanitize input to plausible Docker API version ranges (1.x to 2.x)

Example fix

// before
ApiVersion.parse(readFromUserInput)
// after
if (!readFromUserInput.matches("\\d+\\.\\d+")) throw new IllegalArgumentException("bad version");
ApiVersion.parse(readFromUserInput)

if (value == null || !value.matches("\\d+\\.\\d+")) {
    throw new IllegalArgumentException("Version must be \\d+.\\d+: " + value);
}
ApiVersion.parse(value);

try { ApiVersion.parse(value); } catch (IllegalArgumentException ex) { log.warn("Unparseable Docker API version '{}', falling back to default", value); return ApiVersion.of(1, 24); }

When it happens

Trigger: Passing a version string that passes the regex but fails Integer.parseInt (overflow values like '99999999999999.0'), or a value bypassing the Assert.hasText check.

Common situations: Parsing Docker API versions from unexpected daemon responses; user input with absurdly large version numbers; malformed environment-provided version strings.

Related errors

• 'value' [{}] must be in the form 'os[/architecture[/variant]
• Invalid value for option '--environment'. Expected 'NAME=VAL
• Each image building cache can be configured only once
• Invalid Docker configuration, either context or host can be
• Invalid Docker {} registry configuration, either token or us

AI-assisted analysis of spring-projects/spring-boot@270dfe353f (2026-08-11). Data as JSON: /api/errors/7a1a108fd712765d. Report an issue: GitHub.