alibaba/spring-cloud-alibaba · error · IllegalStateException

Incompatible %s instance. Fallback/fallbackFactory of type %

Error message

Incompatible %s instance. Fallback/fallbackFactory of type %s is not assignable to %s for feign client %s

What it means

After resolving the fallback instance, SentinelFeign verifies it is assignable to the feign client's target type with targetType.isAssignableFrom(fallbackType). If the fallback or fallbackFactory produces an instance that does not implement the feign interface, this formatted IllegalStateException is thrown, naming the role, the actual type, and the expected target type.

Source

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

								"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");
						}
						fallbackType = fallbackInstance.getClass();
					}

					if (!targetType.isAssignableFrom(fallbackType)) {
						throw new IllegalStateException(String.format(
								"Incompatible %s instance. Fallback/fallbackFactory of type %s is not assignable to %s for feign client %s",
								type, fallbackType, targetType, name));
					}
					return fallbackInstance;
				}
			});

			super.contract(new SentinelContractHolder(contract));
			return super.internalBuild();
		}

		private @Nullable Object getFieldValue(Object instance, String fieldName) {
			@Nullable Field field = ReflectionUtils.findField(instance.getClass(), fieldName);
			if (field == null) {
				return null;
			}
			field.setAccessible(true);
			try {

View on GitHub (pinned to 115d590110)

Solutions

Make the fallback class implement the feign client interface exactly.
For a fallbackFactory, ensure create(Throwable) returns an instance assignable to the feign interface.
Use the interface type (not a concrete class) in the @FeignClient generic bound where applicable.

Example fix

// before
public class MyApiFallback { public Result foo() { ... } }
// after
public class MyApiFallback implements MyApi { @Override public Result foo() { ... } }

Defensive patterns

Strategy: type-guard

Validate before calling

void assertFallbackAssignable(Class<?> fallbackType, Class<?> feignInterface) {
  if (!feignInterface.isAssignableFrom(fallbackType))
    throw new IllegalStateException(fallbackType + " is not a " + feignInterface);
}

Type guard

static boolean fallbackMatches(Class<?> fallbackType, Class<?> feignInterface) {
  return feignInterface.isAssignableFrom(fallbackType);
}

Prevention

Make every fallback implement the feign interface.
Unit-test that fallbackFactory.create(ex) returns an assignable type.
Re-run the type check after interface changes.

When it happens

Trigger: @FeignClient(fallback = WrongType.class) where WrongType does not implement the feign interface; a fallbackFactory whose create(...) returns an object of an unrelated type.

Common situations: Creating a fallback class and forgetting to 'implements MyFeignClient'. A fallbackFactory returning a generic Object or a map-based proxy that lacks the interface.

Related errors

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