spring-projects/spring-framework · error · IllegalStateException

Failed to load Class [{}] from ClassLoader [{}]

Error message

Failed to load Class [{}] from ClassLoader [{}]

What it means

During AOT bean-definition code generation, BeanDefinitionPropertiesCodeGenerator parses a fully-qualified factory/lookup method name; if the class portion of that name cannot be loaded by the bean class's ClassLoader, this IllegalStateException is thrown. It indicates a method reference points at a type that is not visible to the bean's classloader at AOT time.

Source

Thrown at spring-beans/src/main/java/org/springframework/beans/factory/aot/BeanDefinitionPropertiesCodeGenerator.java:182

					.collect(CodeBlock.joining(", "));
			code.addStatement(format, BEAN_DEFINITION_VARIABLE, arguments);
		}
	}

	private void addInitDestroyHint(Class<?> beanUserClass, String methodName) {
		Class<?> methodDeclaringClass = beanUserClass;

		// Parse fully-qualified method name if necessary.
		int indexOfDot = methodName.lastIndexOf('.');
		if (indexOfDot > 0) {
			String className = methodName.substring(0, indexOfDot);
			methodName = methodName.substring(indexOfDot + 1);
			if (!beanUserClass.getName().equals(className)) {
				try {
					methodDeclaringClass = ClassUtils.forName(className, beanUserClass.getClassLoader());
				}
				catch (Throwable ex) {
					throw new IllegalStateException("Failed to load Class [" + className +
							"] from ClassLoader [" + beanUserClass.getClassLoader() + "]", ex);
				}
			}
		}

		Method method = ReflectionUtils.findMethod(methodDeclaringClass, methodName);
		if (method != null) {
			this.hints.reflection().registerMethod(method, ExecutableMode.INVOKE);
			Method publiclyAccessibleMethod = ClassUtils.getPubliclyAccessibleMethodIfPossible(method, beanUserClass);
			if (!publiclyAccessibleMethod.equals(method)) {
				this.hints.reflection().registerMethod(publiclyAccessibleMethod, ExecutableMode.INVOKE);
			}
		}
	}

	private void addConstructorArgumentValues(CodeBlock.Builder code, BeanDefinition beanDefinition) {
		ConstructorArgumentValues constructorValues = beanDefinition.getConstructorArgumentValues();
		Map<Integer, ValueHolder> indexedValues = constructorValues.getIndexedArgumentValues();

View on GitHub (pinned to e8729d0438)

Solutions

1. Correct the class name in the factory-method/override reference to the current FQN.
2. Add the missing class/module to the classpath used for AOT processing.
3. Remove the obsolete bean definition or method-override entry.

Example fix

<!-- before -->
<bean class="com.acme.OldService" factory-method="com.acme.removed.Helper.create"/>
<!-- after -->
<bean class="com.acme.OldService" factory-method="com.acme.Helper.create"/>

int dot = methodName.lastIndexOf('.');
if (dot > 0) {
  String cls = methodName.substring(0, dot);
  if (!ClassUtils.isPresent(cls, beanClass.getClassLoader())) {
    throw new IllegalStateException("Class " + cls + " not loadable by " + beanClass.getClassLoader());
  }
}

When it happens

Trigger: A bean definition's factory-method or overrides reference a fully-qualified method whose declaring class (the prefix before the last '.') is absent from the bean class's ClassLoader during AOT processing.

Common situations: Class removed/renamed in a dependency bump but bean XML/registration still references the old FQN; multi-module build where a class is on the compile classpath but not the AOT/runtime classpath; bean defined in XML with a stale factory-method attribute.

Related errors

• {} cannot be found on {}
• Argument type mismatch: expected '{}' for value [{}]
• Unexpected MethodOverride subclass: {}
• Unsupported executable: {}
• failed to generate code for bean definition

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