junit-team/junit5 · error · JUnitException

${annotationConsumerInstance.getClass().getName()} must be u

Error message

${annotationConsumerInstance.getClass().getName()} must be used with an annotation of type ${annotationType.getName()}

What it means

AnnotationConsumerInitializer.initialize looks for annotations of the type its target consumes on the annotated element; if none are found it throws JUnitException. A custom provider/converter that implements AnnotationConsumer<A> was registered (e.g. via @ArgumentsSource) but the matching annotation A is not present on the test class/method.

Source

Thrown at junit-jupiter-params/src/main/java/org/junit/jupiter/params/support/AnnotationConsumerInitializer.java:61

		new MethodSignature("provideArguments", 2, 1), //
		new MethodSignature("convert", 3, 2));

	private static final Predicate<Method> consumesAnnotation = methodSignatures.stream() //
			.map(signature -> (Predicate<Method>) signature::matches) //
			.reduce(method -> false, Predicate::or);

	private AnnotationConsumerInitializer() {
		/* no-op */
	}

	@SuppressWarnings({ "unchecked", "rawtypes" })
	public static <T> T initialize(AnnotatedElement annotatedElement, T annotationConsumerInstance) {
		if (annotationConsumerInstance instanceof AnnotationConsumer consumer) {
			Class<? extends Annotation> annotationType = findConsumedAnnotationType(annotationConsumerInstance);
			List<? extends Annotation> annotations = findAnnotations(annotatedElement, annotationType);

			if (annotations.isEmpty()) {
				throw new JUnitException(annotationConsumerInstance.getClass().getName()
						+ " must be used with an annotation of type " + annotationType.getName());
			}

			annotations.forEach(annotation -> initializeAnnotationConsumer(consumer, annotation));
		}
		return annotationConsumerInstance;
	}

	private static <T extends Annotation> List<T> findAnnotations(AnnotatedElement annotatedElement,
			Class<T> annotationType) {

		return annotationType.isAnnotationPresent(Repeatable.class)
				? findRepeatableAnnotations(annotatedElement, annotationType)
				: findAnnotation(annotatedElement, annotationType).map(Collections::singletonList).orElse(emptyList());
	}

	private static <T> Class<? extends Annotation> findConsumedAnnotationType(T annotationConsumerInstance) {
		Method method = findMethods(annotationConsumerInstance.getClass(), consumesAnnotation, BOTTOM_UP).get(0);

View on GitHub (pinned to 956246301e)

Solutions

Add the consumed annotation to the @ParameterizedTest method or @ParameterizedClass.
Ensure the annotation declares @Retention(RUNTIME) and an appropriate @Target.
If the provider should be self-contained, register the annotation as a meta-annotation on @ArgumentsSource or use @ArgumentsSource as the carrier.

Example fix

// before
@ParameterizedTest
@ArgumentsSource(MyProvider.class)   // MyProvider consumes @MyAnno
void test(int x) { }

// after
@ParameterizedTest
@MyAnno("x")
@ArgumentsSource(MyProvider.class)
void test(int x) { }

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the consumed annotation is actually present on the element.
java.lang.reflect.AnnotatedElement el = method;
Class<? extends java.lang.annotation.Annotation> consumed = MyAnno.class;
if (el.getAnnotation(consumed) == null
        && el.getDeclaredAnnotationsByType(consumed).length == 0) {
    throw new IllegalStateException("Missing @" + consumed.getSimpleName()
        + " required by the registered provider");
}

Try / catch

try {
    // run the parameterized test
} catch (JUnitException e) {
    if (e.getMessage().contains("must be used with an annotation of type")) {
        // add the expected annotation to the test element
    } else throw e;
}

Prevention

Keep custom source annotations on the same element as @ArgumentsSource.
Give custom annotations @Retention(RUNTIME) and a fitting @Target.
Document, on the provider, which annotation it consumes.

When it happens

Trigger: Registering `@ArgumentsSource(MyProvider.class)` where MyProvider implements AnnotationConsumer<MyAnnotation>, but the @ParameterizedTest element is missing @MyAnnotation (or it is on the wrong target / non-retained).

Common situations: Authoring a custom source annotation and forgetting to put it on the test; @Target mismatch; annotation not annotated with @Retention(RUNTIME); meta-annotation not picked up across element types.

Related errors

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