What causes "Cannot convert null to primitive value of type %s" in junit-team/junit5?

Change the parameter type from primitive to its wrapper type (int → Integer, boolean → Boolean) to allow null

junit-team/junit5 · error · ArgumentConversionException

Cannot convert null to primitive value of type %s

Error message

Cannot convert null to primitive value of type %s

What it means

Thrown by DefaultArgumentConverter.convert() when the source object is null and the target type is a primitive (int, long, boolean, byte, short, double, float, char). Primitives in Java cannot hold null values — null can only be assigned to reference types (including wrapper types like Integer). The error message includes the primitive type name.

Source

Thrown at junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/DefaultArgumentConverter.java:78

	public final @Nullable Object convert(@Nullable Object source, ParameterContext context) {
		Class<?> targetType = context.getParameter().getType();
		ClassLoader classLoader = getClassLoader(context.getDeclaringExecutable().getDeclaringClass());
		return convert(source, targetType, classLoader);
	}

	@Override
	public final @Nullable Object convert(@Nullable Object source, FieldContext context)
			throws ArgumentConversionException {

		Class<?> targetType = context.getField().getType();
		ClassLoader classLoader = getClassLoader(context.getField().getDeclaringClass());
		return convert(source, targetType, classLoader);
	}

	public final @Nullable Object convert(@Nullable Object source, Class<?> targetType, ClassLoader classLoader) {
		if (source == null) {
			if (targetType.isPrimitive()) {
				throw new ArgumentConversionException(
					"Cannot convert null to primitive value of type " + targetType.getTypeName());
			}
			return null;
		}

		if (ReflectionUtils.isAssignableTo(source, targetType)) {
			return source;
		}

		if (source instanceof String string) {
			try {
				return convert(string, targetType, classLoader);
			}
			catch (ConversionException ex) {
				throw new ArgumentConversionException(ex.getMessage(), ex);
			}
		}

View on GitHub (pinned to f070c699a0)

Solutions

Change the parameter type from primitive to its wrapper type (int → Integer, boolean → Boolean) to allow null
Ensure the argument source never provides null for primitive parameters — replace nulls with default values (0, false, etc.)
Remove @NullSource from tests with primitive parameters, or move null tests to a separate test with a wrapper-type parameter
For CSV sources, configure emptyValue handling or use @CsvFileSource with explicit null handling

Example fix

// before — primitive parameter with possible null source
@ParameterizedTest
@NullSource
@ValueSource(ints = {1, 2, 3})
void test(int value) { } // null → Cannot convert null to primitive

// after — use wrapper type to allow null
@ParameterizedTest
@NullSource
@ValueSource(ints = {1, 2, 3})
void test(Integer value) {
    if (value == null) return; // handle null explicitly
    // ... test logic
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate parameter types against possible null arguments before running
import java.lang.reflect.Parameter;

static void validatePrimitiveParamsForNull(Method testMethod) {
    for (Parameter p : testMethod.getParameters()) {
        if (p.getType().isPrimitive()) {
            System.out.println("WARNING: Parameter " + p.getName()
                + " is primitive (" + p.getType() + ")."
                + " If the source may provide null, use the wrapper type instead.");
        }
    }
}

Type guard

// Type guard: check if a parameter type can accept null
static boolean canAcceptNull(Class<?> type) {
    return !type.isPrimitive(); // primitives cannot be null
}

// Usage: if (!canAcceptNull(paramType) && mayProduceNull(source)) { /* fix needed */ }

Prevention

Use wrapper types (Integer, Boolean, etc.) instead of primitives for parameterized test parameters that may receive null
Never combine @NullSource with primitive parameters — split null cases into a separate test with wrapper types
For CSV sources, check for empty columns and either provide defaults or use wrapper parameter types

When it happens

Trigger: A @ParameterizedTest parameter or @Parameter field is a primitive type (e.g., int, boolean) and the argument source provides null for that position. This happens with CSV sources that have empty fields (which may parse as null), @NullSource, or custom ArgumentsProvider returning null values. The converter receives null and sees targetType.isPrimitive() == true.

Common situations: CSV parameterized tests where a column is sometimes empty, and the parameter is a primitive int. Using @NullSource alongside @ValueSource for a primitive parameter. Custom ArgumentsProvider that conditionally returns null for some invocations. JSON/YAML-based argument sources where a field is omitted and deserializes to null.

Related errors

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