spring-projects/spring-framework · error · BeanInstantiationException

Unresolvable class definition

Error message

Unresolvable class definition

What it means

Thrown as BeanInstantiationException by instantiateClass(Class) when getDeclaredConstructor() raises a LinkageError (typically NoClassDefFoundError or UnsatisfiedLinkError) rather than NoSuchMethodException. It signals that the class's definition cannot be resolved at runtime, usually because a referenced type or resource is missing (BeanUtils.java:146-148).

Source

Thrown at spring-beans/src/main/java/org/springframework/beans/BeanUtils.java:147

	 * @see Constructor#newInstance
	 */
	public static <T> T instantiateClass(Class<T> clazz) throws BeanInstantiationException {
		Assert.notNull(clazz, "Class must not be null");
		if (clazz.isInterface()) {
			throw new BeanInstantiationException(clazz, "Specified class is an interface");
		}
		Constructor<T> ctor;
		try {
			ctor = clazz.getDeclaredConstructor();
		}
		catch (NoSuchMethodException ex) {
			ctor = findPrimaryConstructor(clazz);
			if (ctor == null) {
				throw new BeanInstantiationException(clazz, "No default constructor found", ex);
			}
		}
		catch (LinkageError err) {
			throw new BeanInstantiationException(clazz, "Unresolvable class definition", err);
		}
		return instantiateClass(ctor);
	}

	/**
	 * Instantiate a class using its no-arg constructor and return the new instance
	 * as the specified assignable type.
	 * <p>Useful in cases where the type of the class to instantiate (clazz) is not
	 * available, but the type desired (assignableTo) is known.
	 * <p>Note that this method tries to set the constructor accessible if given a
	 * non-accessible (that is, non-public) constructor.
	 * @param clazz class to instantiate
	 * @param assignableTo type that clazz must be assignableTo
	 * @return the new instance
	 * @throws BeanInstantiationException if the bean cannot be instantiated
	 * @see Constructor#newInstance
	 */
	@SuppressWarnings("unchecked")

View on GitHub (pinned to e8729d0438)

Solutions

1. Inspect the wrapped LinkageError (cause) to find the missing class name, then add the missing dependency to the runtime classpath.
2. Run 'mvn dependency:tree' / 'gradle dependencies' to confirm the required artifact resolves at runtime scope.
3. If shading, ensure includes cover all referenced classes (fix the shade plugin filters).
4. Pin compatible library versions so referenced types still exist (avoid version mismatches).

Example fix

// before: Foo extends RemovedSuperClass -> NoClassDefFoundError
BeanUtils.instantiateClass(Foo.class);

// after
// add the dependency providing RemovedSuperClass to runtime classpath
<dependency><groupId>org.example</groupId><artifactId>core</artifactId><version>2.x</version></dependency>

// Best-effort: confirm class is loadable & has no missing references
try { clazz.getDeclaredConstructor(); }
catch (NoClassDefFoundError | LinkageError e) { /* report missing dependency before calling Spring */ }

public static boolean isLinkageClean(Class<?> c) {
  try { c.getDeclaredConstructor(); return true; }
  catch (LinkageError | NoSuchMethodException e) { return false; }
}

try { BeanUtils.instantiateClass(clazz); }
catch (BeanInstantiationException e) {
  if (e.getCause() instanceof LinkageError le) {
    // le.getMessage() names the missing class; add the dependency
  }
}

When it happens

Trigger: instantiateClass(Foo.class) where Foo references a type that is not on the classpath/module path, or whose static initializer fails, triggering a LinkageError during reflective constructor lookup.

Common situations: Missing optional dependency at runtime (class present at compile time, absent at runtime); fat-jar shading that dropped a transitive class; module path misconfiguration; a superclass/interface removed in a newer library version; failed static initializer.

Related errors

• Specified class is an interface
• Is it an abstract class?
• Is the constructor accessible?
• No default constructor found
• Illegal arguments for constructor

AI-assisted analysis of spring-projects/spring-framework@e8729d0438 (2026-08-04). Data as JSON: /data/errors/1ec6e1415ab0dd4d.json. Report an issue: GitHub.