alibaba/spring-cloud-alibaba · error · IllegalStateException

FeignClientFactoryBean not found for {targetType}

Error message

FeignClientFactoryBean not found for {targetType}

What it means

To resolve a feign client's fallback/fallbackFactory, SentinelFeign looks up the FeignClientFactoryBean that registered the client. Depending on the lazy-init flag it either reads an attribute from the bean definition or fetches the factory bean by '&'+name. If neither yields a FeignClientFactoryBean, this IllegalStateException is thrown at client build time.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-sentinel/src/main/java/com/alibaba/cloud/sentinel/feign/SentinelFeign.java:113

					// If you need the attributes to be resolved lazily, set the property value to true.
					Boolean isLazyInit = ctx.getEnvironment()
							.getProperty(FEIGN_LAZY_ATTR_RESOLUTION, Boolean.class, false);
					if (isLazyInit) {
						/*
						 * Due to the change of the initialization sequence,
						 * BeanFactory.getBean will cause a circular dependency. So
						 * FeignClientFactoryBean can only be obtained from BeanDefinition
						 */
						feignClientFactoryBean = (FeignClientFactoryBean) def
								.getAttribute("feignClientsRegistrarFactoryBean");
					}
					else {
						feignClientFactoryBean = (FeignClientFactoryBean) ctx
								.getBean("&" + target.type().getName());
					}
					if (feignClientFactoryBean == null) {
						throw new IllegalStateException("FeignClientFactoryBean not found for " + target.type().getName());
					}
					Class fallback = feignClientFactoryBean.getFallback();
					Class fallbackFactory = feignClientFactoryBean.getFallbackFactory();
					String beanName = feignClientFactoryBean.getContextId();
					if (!StringUtils.hasText(beanName)) {
						@Nullable Object nameValue = getFieldValue(feignClientFactoryBean, "name");
						beanName = nameValue != null ? (String) nameValue : "unknown";
					}

					Object fallbackInstance;
					FallbackFactory fallbackFactoryInstance;
					// check fallback and fallbackFactory properties
					if (void.class != fallback) {
						fallbackInstance = getFromContext(beanName, "fallback", fallback,
								target.type());
						return new SentinelInvocationHandler(target, dispatch,
								new FallbackFactory.Default(fallbackInstance));
					}

View on GitHub (pinned to 115d590110)

Solutions

1. Register clients with @FeignClients and let FeignClientFactoryBean manage them.
2. If using a non-lazy path, ensure the FactoryBean is registered under the conventional '&<fully-qualified-name>' bean name.
3. Align spring-cloud-openfeign and spring-cloud-alibaba-sentinel versions so the registrar attribute key matches.
4. Avoid providing your own bean definition that shadows the FeignClientFactoryBean.

Example fix

// before: manual bean registration without factory bean
@Bean MyApi myApi() { return FeignClientBuilder.create().api(MyApi.class); }
// after
@FeignClient(name = "myApi", fallback = MyApiFallback.class)
public interface MyApi { ... }

void ensureFactoryBean(BeanDefinitionRegistry r, String name) {
  if (!r.containsBeanDefinition(name) && !r.containsBeanDefinition("&" + name))
    throw new IllegalStateException("No FeignClientFactoryBean for " + name + "; register via @FeignClient");
}

When it happens

Trigger: A @FeignClient whose registration did not go through FeignClientsRegistrar (so the 'feignClientsRegistrarFactoryBean' attribute is absent) and the '&name' bean lookup also fails. Custom feign client registration that bypasses the standard factory bean.

Common situations: Registering feign clients via FeignClientBuilder.create() instead of @FeignClients/FeignClientFactoryBean. A framework version mismatch where the attribute key changed. Manually providing a feign client bean of the wrong type.

Related errors

• FeignClientFactory not initialized
• No %s instance of type %s found for feign client %s
• {type} create fail
• {type} FactoryBean returned null
• Incompatible %s instance. Fallback/fallbackFactory of type %

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/88d1fe644e5463ce. Report an issue: GitHub.