junit-team/junit5 · error · JUnitException

Failed to transform configuration parameter with key

Error message

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

What it means

ConfigurationParameters.get(String, Function) lets a caller read a config value and transform it (e.g. parse to int/boolean/duration). If the transformer throws any Exception while applied to the raw string value, it is wrapped in a JUnitException naming the key and the offending value. This is the engine's generic typed-access failure for configuration parameters.

Solutions

Inspect the error message for the exact key and initial value, then correct the value at its source (system property, junit.properties, --config, build config).
Prefer the typed helpers where available — getBoolean(key) is more forgiving than a hand-written parser.
If you own the transformer, make it throw a clear IllegalArgumentException with guidance for valid values, so the wrapped message is actionable.
Confirm the configuration parameter key name matches the extension's documented property (typos yield the raw string hitting the transformer).

Example fix

// before
String raw = config.get("junit.jupiter.execution.timeout.test.method.mode").orElse(null);
int n = Integer.parseInt(raw); // throws if raw is "adada"
// after — use the typed accessor / safe transform
boolean parallel = config.getBoolean("junit.jupiter.execution.parallel.enabled").orElse(false);
Optional<Integer> n = config.get("my.count", Integer::parseInt); // JUnitException names key+value on failure

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate config values you control before they reach an engine/extension that will transform them.
String raw = config.get("my.extension.count").orElse(null);
if (raw != null) {
  try { Integer.parseInt(raw); }
  catch (NumberFormatException e) { throw new IllegalArgumentException("my.extension.count must be an integer, got: " + raw); }
}

Try / catch

// Catch JUnitException around the typed accessor when user-supplied values may be invalid.
try {
  Optional<Integer> n = configurationParameters.get("my.extension.count", Integer::parseInt);
} catch (org.junit.platform.commons.JUnitException e) {
  // message names the key and the offending value
  throw new IllegalArgumentException(e.getMessage(), e);
}

Prevention

Prefer built-in typed accessors (getBoolean) over hand-rolled parsers.
Document every configuration parameter's expected format in your extension's user guide.
Surface transformer failures with actionable IllegalArgumentException messages from your own transformer.

When it happens

Trigger: Calling configurationParameters.get(key, transformer) where the stored value cannot be transformed — e.g. get("timeout", Integer::parseInt) with a non-numeric value; a custom transformer that throws IllegalArgumentException on invalid enum names; a duration transformer given a malformed unit.

Common situations: A user sets --config junit.foo.bar=someGarbage and an extension/engine tries to parse it; build-tool (Gradle/Maven) plugins passing through a mistyped value; a defaults file with a stale value after upgrading an extension that changed the expected format.

Related errors

AI-assisted analysis of junit-team/junit5@f070c699a0 (2026-08-11). Data as JSON: /api/errors/b68498eca95479ed. Report an issue: GitHub.

Appendix: 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 f070c699a0)