alibaba/spring-cloud-alibaba · error · IllegalStateException

FeignClientFactory not initialized

Error message

FeignClientFactory not initialized

What it means

The private helper getFromContext, used to resolve fallback or fallbackFactory instances from the FeignClientFactory child context, begins by asserting the factory is non-null. This is a defensive re-check in a code path that should already have been guarded by error 111; if reached with a null factory it means the builder lost its reference mid-resolution.

Source

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

						return new SentinelInvocationHandler(target, dispatch,
								new FallbackFactory.Default(fallbackInstance));
					}
					if (void.class != fallbackFactory) {
						fallbackFactoryInstance = (FallbackFactory) getFromContext(
								beanName, "fallbackFactory", fallbackFactory,
								FallbackFactory.class);
						return new SentinelInvocationHandler(target, dispatch,
								fallbackFactoryInstance);
					}

					return new SentinelInvocationHandler(target, dispatch);
				}

				private Object getFromContext(String name, String type,
						Class fallbackType, Class targetType) {
					FeignClientFactory factory = Builder.this.feignClientFactory;
					if (factory == null) {
						throw new IllegalStateException("FeignClientFactory not initialized");
					}
					Object fallbackInstance = factory.getInstance(name,
							fallbackType);
					if (fallbackInstance == null) {
						throw new IllegalStateException(String.format(
								"No %s instance of type %s found for feign client %s",
								type, fallbackType, name));
					}
					// when fallback is a FactoryBean, should determine the type of instance
					if (fallbackInstance instanceof FactoryBean<?> factoryBean) {
						try {
							fallbackInstance = factoryBean.getObject();
						}
						catch (Exception e) {
							throw new IllegalStateException(type + " create fail", e);
						}
						if (fallbackInstance == null) {
							throw new IllegalStateException(type + " FactoryBean returned null");

View on GitHub (pinned to 115d590110)

Solutions

1. Apply the same fixes as error 111: ensure the SentinelFeign builder carries a non-null FeignClientFactory.
2. Do not subclass/replace SentinelFeign.Builder in a way that drops the factory field.
3. Confirm feign + sentinel starters versions are compatible.

void buildWithFactory(SentinelFeign.Builder b) {
  if (b.getFeignClientFactory() == null) throw new IllegalStateException("feignClientFactory must be set before build");
  b.build();
}

try { resolveFallback(factory, type); }
catch (IllegalStateException e) { if (factory == null) { factory = refreshFactory(); /* retry once */ } else throw e; }

When it happens

Trigger: Same root causes as error 111 but encountered after the initial build, during per-client fallback resolution when the builder's feignClientFactory field is null. Theoretically reachable via custom SentinelFeign subclassing that clears the factory.

Common situations: Custom Feign builder that nulls out the factory. Race during reconfiguration. Version skew in the Sentinel feign integration.

Related errors

• FeignClientFactoryBean not found for {targetType}
• 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/76836581135707c7. Report an issue: GitHub.