junit-team/junit5 · error · JUnitException

Failed to initialize AnnotationConsumer: ${instance}

Error message

Failed to initialize AnnotationConsumer: ${instance}

What it means

AnnotationConsumerInitializer.initializeAnnotationConsumer calls instance.accept(annotation) inside a try and wraps any Exception as JUnitException. The custom AnnotationConsumer's accept method threw while validating or storing the annotation - typically because an annotation attribute failed a precondition.

Source

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

	@SuppressWarnings("unchecked")
	private static Class<? extends Annotation> getAnnotationType(Method method) {
		int annotationIndex = methodSignatures.stream() //
				.filter(signature -> signature.matches(method)) //
				.findFirst() //
				.map(MethodSignature::annotationParameterIndex) //
				.orElse(0);

		return (Class<? extends Annotation>) method.getParameterTypes()[annotationIndex];
	}

	private static <A extends Annotation> void initializeAnnotationConsumer(AnnotationConsumer<A> instance,
			A annotation) {
		try {
			instance.accept(annotation);
		}
		catch (Exception ex) {
			throw new JUnitException("Failed to initialize AnnotationConsumer: " + instance, ex);
		}
	}

	/**
	 * Annotation-consuming method signature.
	 */
	private record MethodSignature(String methodName, int parameterCount, int annotationParameterIndex) {

		boolean matches(Method method) {
			return method.getName().equals(methodName) //
					&& method.getParameterCount() == parameterCount //
					&& method.getParameterTypes()[annotationParameterIndex].isAnnotation();
		}
	}

}

View on GitHub (pinned to 956246301e)

Solutions

1. Read the cause of the JUnitException - it carries the real validation message from accept.
2. Fix the annotation attributes to satisfy the provider's accept contract.
3. If you author the provider, throw a precise exception (PreconditionViolationException) with an actionable message.

Example fix

// before
@MyAnno(value = "")   // provider's accept rejects blank value

// after
@MyAnno(value = "valid")

// Validate annotation attributes the way the provider's accept() will, before registration.
String value = annotation.value();
if (value == null || value.isBlank()) {
    throw new IllegalArgumentException("@MyAnno.value must not be blank");
}

try {
    // run the parameterized test that initializes the provider
} catch (JUnitException e) {
    if (e.getMessage().contains("Failed to initialize AnnotationConsumer")) {
        Throwable cause = e.getCause();
        // read cause's message and fix the offending annotation attribute
    } else throw e;
}

When it happens

Trigger: A custom provider's accept(A) method throws (e.g. a Preconditions.check on an attribute), surfacing during extension initialization before any test runs.

Common situations: Custom annotation with an invalid attribute (blank string, negative number, malformed value); NPE inside accept; third-party extension that validates its annotation eagerly.

Related errors

• ${annotationConsumerInstance.getClass().getName()} must be u
• %s cannot convert to type [%s]. Only target type [%s] is sup
• AnnotationBasedArgumentsProvider does not override the provi
• Please implement provideArguments(ParameterDeclarations, Ext
• ArgumentsProvider does not override the provideArguments(Par

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