junit-team/junit5 · error · JUnitException

Failed to transform configuration parameter with key '%s' an

Error message

Failed to transform configuration parameter with key '%s' and initial value '%s'

What it means

Thrown by the ConfigurationParameters.get(String, Function) default method (line 120-132) when the user-supplied transformer throws any exception while converting a configuration parameter value. The library wraps the original exception in a JUnitException so callers get a single, consistent failure type naming the offending key and initial value. This is the standard mechanism for engines/extensions that parse typed config values (e.g. integers, durations).

Source

Thrown at junit-platform-engine/src/main/java/org/junit/platform/engine/ConfigurationParameters.java:129

	 * @return an {@code Optional} containing the value; never {@code null}
	 * but potentially empty
	 *
	 * @since 1.3
	 * @see #getBoolean(String)
	 * @see System#getProperty(String)
	 * @see #CONFIG_FILE_NAME
	 */
	@API(status = STABLE, since = "1.3")
	default <T> Optional<T> get(String key, Function<? super String, ? extends @Nullable T> transformer) {
		Preconditions.notNull(transformer, "transformer must not be null");
		return get(key).map(input -> {
			try {
				return transformer.apply(input);
			}
			catch (Exception ex) {
				String message = "Failed to transform configuration parameter with key '%s' and initial value '%s'".formatted(
					key, input);
				throw new JUnitException(message, ex);
			}
		});
	}

	/**
	 * Get the keys of all configuration parameters stored in this
	 * {@code ConfigurationParameters}.
	 *
	 * @return the set of keys contained in this {@code ConfigurationParameters}
	 */
	@API(status = STABLE, since = "1.9")
	Set<String> keySet();

}

View on GitHub (pinned to 956246301e)

Solutions

Read the caused-by exception to identify the parse failure and the exact value, then correct the property in junit-platform.properties or the JVM system property.
Make your transformer defensive: sanitize/validate the raw string before parsing, or return null (treated as absent) instead of throwing.
Confirm whether the value originates from junit-platform.properties, a system property, or a programmatic LauncherFactory request and fix it at that source.
Run with debug logging to see which ConfigurationParameters key is being transformed when the error surfaces deep in engine code.

Example fix

// before
int parallelism = config.get("fixed.parallelism", Integer::valueOf).orElse(1); // throws on 'abc'

// after
int parallelism = config.get("fixed.parallelism", raw -> {
    try { return Integer.valueOf(raw); }
    catch (NumberFormatException e) { return null; } // treated as absent
}).orElse(1);
// and in junit-platform.properties: fixed.parallelism=4

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the value parses *before* handing it to the framework transformer
Optional<String> raw = config.get("my.key");
if (raw.isPresent()) {
    try { Integer.parseInt(raw.get()); }
    catch (NumberFormatException e) { throw new IllegalStateException("my.key must be integer: " + raw.get(), e); }
}

Try / catch

try {
    return config.get("my.key", Integer::valueOf).orElse(defaultValue);
} catch (JUnitException e) {
    // caused-by has the real parse error
    log.warn("bad value for my.key, using default", e.getCause());
    return defaultValue;
}

Prevention

Validate junit-platform.properties values in a startup smoke check.
Use defensive transformers that return null (treated as absent) on parse failure instead of throwing.
Keep a single source of truth for each configuration parameter's parser.

When it happens

Trigger: Calling configurationParameters.get("some.key", Integer::valueOf) where the resolved value is non-numeric; any transformer lambda (Duration.parse, URI::new, custom parser) that throws on the stored value. The value comes from the layered lookup: direct params, then JVM system property, then junit-platform.properties.

Common situations: Setting junit.platform.* properties to invalid values (e.g. junit.jupiter.execution.parallel.config.fixed.parallelism=abc); a system property -Djunit.jupiter.conditions.deactivate=malformed colliding with a transformer; version upgrades that change accepted formats; typos in junit-platform.properties.

Related errors

AI-assisted analysis of junit-team/junit5@956246301e (2026-08-04). Data as JSON: /data/errors/b68498eca95479ed.json. Report an issue: GitHub.