spring-projects/spring-boot · error · InvalidUserDataException

Invalid value for option '--environment'. Expected…

Error message

Invalid value for option '--environment'. Expected 'NAME=VALUE' but got '{}'.

What it means

Thrown by BootBuildImage.asMap when parsing command-line '--environment' option values. Each value must be of the form 'NAME=VALUE'. The code finds the index of '=' and throws InvalidUserDataException if the index is <= 0, meaning either there is no '=' at all, or the name is empty (e.g. '=VALUE'). This is a user input validation error at option-parsing time.

Solutions

1. Ensure every --environment value is 'NAME=VALUE' with a non-empty NAME: e.g. '--environment BP_JVM_VERSION=21'.
2. If setting multiple, repeat the flag: '--environment BP_JVM_VERSION=21 --environment BPE_DEBUG=true'.
3. Quote values containing spaces or special characters: '--environment "BPE_GREETING=hello world"'.
4. Validate env var strings programmatically before passing them if generating them in a script.

Example fix

// before
gradle bootBuildImage --environment BP_JVM_VERSION
// after
gradle bootBuildImage --environment BP_JVM_VERSION=21

// Validate environment strings before passing them to the task.
void validateEnvVars(List<String> vars) {
    for (String v : vars) {
        int idx = v.indexOf('=');
        if (idx <= 0) {
            throw new IllegalArgumentException("Invalid env var (expected NAME=VALUE): " + v);
        }
    }
}

When it happens

Trigger: Passing '--environment FOO' (missing '=value'), '--environment =bar' (empty name), or '--environment FOO_BAR' (no equals sign) to the bootBuildImage task on the Gradle command line or in the task's environment configuration.

Common situations: Typing an env var without a value separator. Copying an env var from a shell 'export FOO' syntax into the Gradle option. Using a space instead of '='. Setting an env var name that is empty. Common when scripting bootBuildImage in CI.

Related errors

• Each image building cache can be configured only once
• 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…
• Could not save the project, the server did not set a…

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

Appendix: source

Thrown at build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.java:119

		getCleanCache().convention(false);
		getVerboseLogging().convention(false);
		getPublish().convention(false);
		this.buildWorkspace = getProject().getObjects().newInstance(LocalCacheSpec.class);
		this.buildCache = getProject().getObjects().newInstance(CacheSpec.class);
		this.launchCache = getProject().getObjects().newInstance(LocalCacheSpec.class);
		this.docker = getProject().getObjects().newInstance(DockerSpec.class);
		this.pullPolicy = getProject().getObjects().property(PullPolicy.class);
		getSecurityOptions().convention((Iterable<? extends String>) null);
		getEffectiveEnvironment().putAll(getEnvironment());
		getEffectiveEnvironment().putAll(getEnvironmentFromCommandLine().map(BootBuildImage::asMap));
	}

	private static Map<String, String> asMap(List<String> variables) {
		Map<String, String> environment = new LinkedHashMap<>();
		for (String variable : variables) {
			int index = variable.indexOf('=');
			if (index <= 0) {
				throw new InvalidUserDataException(
						"Invalid value for option '--environment'. Expected 'NAME=VALUE' but got '" + variable + "'.");
			}
			String name = variable.substring(0, index);
			String value = variable.substring(index + 1);
			environment.put(name, value);
		}
		return environment;
	}

	/**
	 * Returns the property for the archive file from which the image will be built.
	 * @return the archive file property
	 */
	@InputFile
	@PathSensitive(PathSensitivity.RELATIVE)
	public abstract RegularFileProperty getArchiveFile();

	/**

View on GitHub (pinned to 270dfe353f)