spring-projects/spring-ai · error · IllegalArgumentException

Functional bean with name

Error message

Functional bean with name %s does not exist in the context.

What it means

Thrown when TypeResolverHelper needs to inspect a bean definition to resolve a functional bean's tool types, but the Spring context has no bean registered under the given name. It converts Spring's NoSuchBeanDefinitionException into an IllegalArgumentException naming the missing functional bean.

Solutions

  1. Verify the bean name matches exactly the @Bean method name registered in the GenericApplicationContext
  2. Check that the configuration class defining the functional bean is actually scanned/registered in the same context
  3. Confirm no @Conditional annotation or active profile is preventing the bean from being created
  4. Catch NoSuchBeanDefinitionException earlier or use applicationContext.containsBeanDefinition(beanName) before resolution

Example fix

// before
ToolCallbacks.from(applicationContext, "fucntionBean");
// after
if (applicationContext.containsBeanDefinition("functionBean")) {
    ToolCallbacks.from(applicationContext, "functionBean");
}
Defensive patterns

Strategy: validation

Validate before calling

if (!applicationContext.containsBeanDefinition(beanName)) {
    throw new IllegalStateException("Bean '" + beanName + "' is not registered; check @Bean name and context");
}

Prevention

When it happens

Trigger: Calling tool resolution for a functional bean (e.g. FunctionCallback wrapper over a @Bean Function/Supplier) where the beanName passed to getBeanDefinition is not registered in the GenericApplicationContext — e.g. a typo in the bean name, the bean defined in a different context/profile, or the functional bean never registered.

Common situations: Renaming or removing a @Bean function while ToolCallbacks still reference the old name; beans defined in a child context or missing @Configuration scan; conditional bean (@ConditionalOnProperty) not created at runtime; typos when passing bean names programmatically.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/5e719b9966d0a28a. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-model/src/main/java/org/springframework/ai/tool/resolution/TypeResolverHelper.java:151

		if (functionType.resolve() != null) {
			return functionType;
		}

		// Handle root bean definitions with factory methods
		if (beanDefinition instanceof RootBeanDefinition rootBeanDefinition) {
			return resolveRootBeanDefinitionType(applicationContext, rootBeanDefinition);
		}

		// Handle @Component beans
		return resolveComponentBeanType(applicationContext, beanDefinition, beanName);
	}

	private static BeanDefinition getBeanDefinition(GenericApplicationContext applicationContext, String beanName) {
		try {
			return applicationContext.getBeanDefinition(beanName);
		}
		catch (NoSuchBeanDefinitionException ex) {
			throw new IllegalArgumentException(
					"Functional bean with name " + beanName + " does not exist in the context.");
		}
	}

	private static ResolvableType resolveRootBeanDefinitionType(GenericApplicationContext applicationContext,
			RootBeanDefinition rootBeanDefinition) {

		Class<?> factoryClass;
		boolean isStatic;

		if (rootBeanDefinition.getFactoryBeanName() != null) {
			factoryClass = applicationContext.getBeanFactory().getType(rootBeanDefinition.getFactoryBeanName());
			isStatic = false;
		}
		else {
			factoryClass = rootBeanDefinition.getBeanClass();
			isStatic = true;
		}

View on GitHub (pinned to 98a7beda4f)