junit-team/junit5 · error · ArgumentConversionException

Cannot convert null to %s; consider setting 'nullable = true

Error message

Cannot convert null to %s; consider setting 'nullable = true'

What it means

Thrown by JavaTimeArgumentConverter when the input argument is null, the target type is a java.time type, and the @JavaTimeConversionPattern annotation does not have nullable = true set (it defaults to false). This converter handles conversion from strings to temporal types (LocalDate, LocalTime, etc.) using a pattern. The message suggests setting 'nullable = true' and includes the target class name.

Source

Thrown at junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/JavaTimeArgumentConverter.java:62

		queries.put(LocalDateTime.class, LocalDateTime::from);
		queries.put(LocalTime.class, LocalTime::from);
		queries.put(OffsetDateTime.class, OffsetDateTime::from);
		queries.put(OffsetTime.class, OffsetTime::from);
		queries.put(Year.class, Year::from);
		queries.put(YearMonth.class, YearMonth::from);
		queries.put(ZonedDateTime.class, ZonedDateTime::from);
		TEMPORAL_QUERIES = Collections.unmodifiableMap(queries);
	}

	@Override
	protected @Nullable Object convert(@Nullable Object input, Class<?> targetClass,
			JavaTimeConversionPattern annotation) {

		if (input == null) {
			if (annotation.nullable()) {
				return null;
			}
			throw new ArgumentConversionException(
				"Cannot convert null to " + targetClass.getName() + "; consider setting 'nullable = true'");
		}
		TemporalQuery<?> temporalQuery = TEMPORAL_QUERIES.get(targetClass);
		if (temporalQuery == null) {
			throw new ArgumentConversionException("Cannot convert to " + targetClass.getName() + ": " + input);
		}
		String pattern = annotation.value();
		DateTimeFormatter formatter = DateTimeFormatter.ofPattern(pattern);
		return formatter.parse(input.toString(), temporalQuery);
	}

}

View on GitHub (pinned to f070c699a0)

Solutions

Set nullable = true on the @JavaTimeConversionPattern annotation to explicitly allow null values
Ensure the argument source never provides null for that parameter by filtering or providing default values
Switch to a wrapper approach: accept null as a String and handle conversion manually, or split null cases into a separate test
If using @CsvSource, provide explicit non-null values for the date column in every row

Example fix

// before — nullable not set, null input fails
@ParameterizedTest
@CsvSource({ "2024-01-01", "" })
void test(@JavaTimeConversionPattern("yyyy-MM-dd") LocalDate date) { }

// after — set nullable = true
@ParameterizedTest
@CsvSource({ "2024-01-01", "" })
void test(@JavaTimeConversionPattern(value = "yyyy-MM-dd", nullable = true) LocalDate date) {
    if (date == null) return; // handle null case
    // ... test logic
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate that the argument source doesn't provide null for non-nullable java.time params
import java.lang.reflect.Parameter;
import org.junit.jupiter.params.converter.JavaTimeConversionPattern;

static void validateJavaTimeParams(Method testMethod) {
    for (Parameter p : testMethod.getParameters()) {
        JavaTimeConversionPattern ann = p.getAnnotation(JavaTimeConversionPattern.class);
        if (ann != null && !ann.nullable() && mayReceiveNull(p)) {
            throw new IllegalStateException(
                "Parameter " + p.getName() + " has @JavaTimeConversionPattern without nullable=true "
                + "but the source may provide null. Set nullable=true or change the source.");
        }
    }
}

Prevention

Set nullable = true on @JavaTimeConversionPattern for any parameter whose source may contain null/empty values
For optional date/time fields in CSV sources, either filter out null rows or use nullable = true with a null check in the test
Separate null-case tests from value-case tests when possible to avoid mixing nullable and non-nullable patterns

When it happens

Trigger: A @ParameterizedTest parameter of type LocalDate (or other java.time type) annotated with @JavaTimeConversionPattern("yyyy-MM-dd") receives a null argument. This can happen with CSV sources where the date column is empty, @NullSource, or custom providers returning null for that parameter.

Common situations: CSV-based tests where a date/time column is optional and sometimes empty. Tests that combine @NullSource or @EmptySource with @JavaTimeConversionPattern-annotated parameters. Database-backed argument sources where a nullable date column returns null for some rows.

Related errors

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