junit-team/junit5 · error · JUnitException

%s must be used with an annotation of type %s

Error message

%s must be used with an annotation of type %s

What it means

Thrown by AnnotationConsumerInitializer.initialize when an AnnotationConsumer instance declares a consumed annotation type but the annotated element (field/method/class) carries none of those annotations. The initializer cannot bind the consumer without the annotation, so it raises a JUnitException naming the consumer class and the expected annotation type.

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

Solutions

1. Annotate the test element with the annotation type the consumer expects (as printed in the message).
2. If the consumer is the wrong one, replace the @ArgumentsSource/@ConvertWith reference with the correct class.
3. Ensure the annotation import matches exactly the type declared by the consumer.

Example fix

// before
@ParameterizedTest
@ArgumentsSource(MyProvider.class)
void test(String x) { }  // MyProvider expects @MyAnnotation

// after
@ParameterizedTest
@MyAnnotation
@ArgumentsSource(MyProvider.class)
void test(String x) { }

// Confirm the test element carries the annotation the consumer expects
Class<? extends Annotation> expected = MyAnnotation.class;
if (!annotatedElement.isAnnotationPresent(expected))
    throw new IllegalStateException("Missing required annotation " + expected.getName());

static boolean hasRequiredAnnotation(AnnotatedElement el, Class<? extends Annotation> ann) {
    return el != null && el.isAnnotationPresent(ann);
}

When it happens

Trigger: Registering an AnnotationConsumer-based argument source/converter that expects, say, @MyAnnotation, but the test element is not annotated with @MyAnnotation. findAnnotations returns an empty list and the initializer throws.

Common situations: Custom argument provider/converter that consumes an annotation, used without that annotation present. Removing or renaming the annotation on the test element while the consumer still expects it. Wrong annotation import causing the type check to fail.

Related errors

• Failed to initialize AnnotationConsumer: %s
• Timeout duration is not in the expected format (<number> [ns
• The charset supplied in %s is invalid
• File [%s] could not be read
• Assumption failed

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