junit-team/junit5 · error · TestInstantiationException

TestInstanceFactory [ ] failed to instantiate test class [ ]

Error message

TestInstanceFactory [%s] failed to instantiate test class [%s]

What it means

Wraps any non-unrecoverable Throwable thrown by a registered TestInstanceFactory.createTestInstance when instantiating a test class. The factory's own exception is only rethrown as-is if it is already a TestInstantiationException; everything else is rewrapped with the factory class name, test class name, and the original message appended.

Solutions

Read the appended cause message (the literal ': ' prefix plus throwable.getMessage()) and fix the underlying instantiation failure.
Verify all constructor parameters of the test class can be resolved by the factory's DI context.
If you wrote the factory, throw TestInstantiationException directly so users get your message verbatim instead of the wrapped form.
Ensure the factory class is not failing due to a missing classpath dependency it needs to build the instance.

Example fix

// before
@Override
public Object createTestInstance(TestInstanceFactoryContext ctx, ExtensionContext ec) {
    return myContainer.getBean(ctx.getTestClass()); // throws when bean missing
}
// after
@Override
public Object createTestInstance(TestInstanceFactoryContext ctx, ExtensionContext ec) {
    Class<?> c = ctx.getTestClass();
    if (!container.containsBean(c))
        throw new TestInstantiationException("No bean for " + c.getName());
    return container.getBean(c);
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    runTests(MyTest.class);
} catch (TestInstantiationException e) {
    log.error("Factory {} failed: {}", e.getMessage(), e.getCause());
    throw e;
}

Prevention

Ensure your TestInstanceFactory can resolve every dependency the test constructor needs.
Throw TestInstantiationException directly from your factory so users see your message unwrapped.
Unit-test the factory outside JUnit to confirm it can build the instance.

When it happens

Trigger: A TestInstanceFactory implementation throwing inside createTestInstance - constructor logic failure, reflection error, missing dependency, NPE from the factory body, or an exception bubbling up from the test class constructor.

Common situations: DI-based factory (Spring/Guice/Koin) cannot resolve a bean, Kotlin object instantiation fails, factory calls Class.newInstance() on a class with no usable constructor, or the factory returns from a blocking lookup that times out.

Related errors

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

Appendix: source

Thrown at junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/ClassBasedTestDescriptor.java:382

		try {
			ExtensionContext actualExtensionContext = extensionContext.get(testInstanceFactory);
			instance = testInstanceFactory.createTestInstance(
				new DefaultTestInstanceFactoryContext(getTestClass(), outerInstance), actualExtensionContext);
		}
		catch (Throwable throwable) {
			UnrecoverableExceptions.rethrowIfUnrecoverable(throwable);

			if (throwable instanceof TestInstantiationException exception) {
				throw exception;
			}

			String message = "TestInstanceFactory [%s] failed to instantiate test class [%s]".formatted(
				testInstanceFactory.getClass().getName(), getTestClass().getName());
			if (StringUtils.isNotBlank(throwable.getMessage())) {
				message += ": " + throwable.getMessage();
			}
			throw new TestInstantiationException(message, throwable);
		}

		if (!getTestClass().isInstance(instance)) {
			String testClassName = getTestClass().getName();
			Class<?> instanceClass = (instance == null ? null : instance.getClass());
			String instanceClassName = (instanceClass == null ? "null" : instanceClass.getName());

			// If the test instance was loaded via a different ClassLoader, append
			// the identity hash codes to the type names to help users disambiguate
			// between otherwise identical "fully qualified class names".
			if (testClassName.equals(instanceClassName)) {
				testClassName += "@" + Integer.toHexString(System.identityHashCode(getTestClass()));
				instanceClassName += "@" + Integer.toHexString(System.identityHashCode(instanceClass));
			}
			String message = "TestInstanceFactory [%s] failed to return an instance of [%s] and instead returned an instance of [%s].".formatted(
				testInstanceFactory.getClass().getName(), testClassName, instanceClassName);

			throw new TestInstantiationException(message);

View on GitHub (pinned to f070c699a0)