spring-projects/spring-boot · error · IllegalArgumentException

'value' [{}] must be in the form 'os[/architecture[/variant]

Error message

'value' [{}] must be in the form 'os[/architecture[/variant]]'

What it means

ImagePlatform.of(value) parses a string of form os[/architecture[/variant]] by splitting on one-or-more slashes ('/+'). If the resulting array has fewer than 1 or more than 3 segments, the value is malformed and the method throws IllegalArgumentException.

Source

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

			builder.append("/").append(this.variant);
		}
		return builder.toString();
	}

	/**
	 * Create a new {@link ImagePlatform} from the given value in the form
	 * {@code os[/architecture[/variant]]}.
	 * @param value the value to parse
	 * @return an {@link ImagePlatform} instance
	 */
	public static ImagePlatform of(String value) {
		Assert.hasText(value, "'value' must not be empty");
		String[] split = value.split("/+");
		return switch (split.length) {
			case 1 -> new ImagePlatform(split[0], null, null);
			case 2 -> new ImagePlatform(split[0], split[1], null);
			case 3 -> new ImagePlatform(split[0], split[1], split[2]);
			default -> throw new IllegalArgumentException(
					"'value' [" + value + "] must be in the form 'os[/architecture[/variant]]'");
		};
	}

	/**
	 * Create a new {@link ImagePlatform} matching the platform information from the
	 * provided {@link Image}.
	 * @param image the image to get platform information from
	 * @return an {@link ImagePlatform} instance
	 */
	public static ImagePlatform from(Image image) {
		return new ImagePlatform(image.getOs(), image.getArchitecture(), image.getVariant());
	}

	/**
	 * Return a JSON-encoded representation of this platform.
	 * @return the JSON string
	 */

View on GitHub (pinned to 270dfe353f)

Solutions

1. Use exactly 'os', 'os/arch', or 'os/arch/variant'
2. Validate by splitting on '/' and asserting 1-3 segments before calling of()
3. Strip trailing slashes and surrounding whitespace before parsing

Example fix

// before
ImagePlatform.of("linux/amd64/v2/extra")
// after
ImagePlatform.of("linux/amd64/v2")

String[] parts = value.split("/+");
if (parts.length < 1 || parts.length > 3) {
    throw new IllegalArgumentException("Platform must be os[/arch[/variant]]: " + value);
}
ImagePlatform.of(value);

static boolean isValidPlatformSpec(String v) { return v != null && v.trim().matches("[^/]+(/[^/]+(/[^/]+)?)?"); }

try { ImagePlatform.of(value); } catch (IllegalArgumentException ex) { log.error("Platform spec must be os[/arch[/variant]]: {}", value); throw ex; }

When it happens

Trigger: Setting BP_IMAGE_PLATFORM (or related configuration) to a value with too many slash segments, e.g. 'linux/amd64/v2/extra'.

Common situations: Copy-pasting a full OCI platform string with extra fields; trailing or duplicated slashes producing unexpected segments; typos in platform spec.

Related errors

• 'value' must contain a well formed version number [{}]
• Error parsing Docker configuration file '{}'
• Docker context '{}' does not exist
• Error parsing Docker context metadata file '{}'
• Error reading Docker configuration file '{}'

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