{"record":{"id":"d3445403321740fb","repo":"alibaba/spring-cloud-alibaba","slug":"incompatible-s-instance-fallback-fallbackfactory","errorCode":null,"errorMessage":"Incompatible %s instance. Fallback/fallbackFactory of type %s is not assignable to %s for feign client %s","messagePattern":"Incompatible (.+?) instance\\. Fallback/fallbackFactory of type (.+?) is not assignable to (.+?) for feign client (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-sentinel/src/main/java/com/alibaba/cloud/sentinel/feign/SentinelFeign.java","lineNumber":171,"sourceCode":"\t\t\t\t\t\t\t\t\"No %s instance of type %s found for feign client %s\",\n\t\t\t\t\t\t\t\ttype, fallbackType, name));\n\t\t\t\t\t}\n\t\t\t\t\t// when fallback is a FactoryBean, should determine the type of instance\n\t\t\t\t\tif (fallbackInstance instanceof FactoryBean<?> factoryBean) {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tfallbackInstance = factoryBean.getObject();\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\t\tthrow new IllegalStateException(type + \" create fail\", e);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif (fallbackInstance == null) {\n\t\t\t\t\t\t\tthrow new IllegalStateException(type + \" FactoryBean returned null\");\n\t\t\t\t\t\t}\n\t\t\t\t\t\tfallbackType = fallbackInstance.getClass();\n\t\t\t\t\t}\n\n\t\t\t\t\tif (!targetType.isAssignableFrom(fallbackType)) {\n\t\t\t\t\t\tthrow new IllegalStateException(String.format(\n\t\t\t\t\t\t\t\t\"Incompatible %s instance. Fallback/fallbackFactory of type %s is not assignable to %s for feign client %s\",\n\t\t\t\t\t\t\t\ttype, fallbackType, targetType, name));\n\t\t\t\t\t}\n\t\t\t\t\treturn fallbackInstance;\n\t\t\t\t}\n\t\t\t});\n\n\t\t\tsuper.contract(new SentinelContractHolder(contract));\n\t\t\treturn super.internalBuild();\n\t\t}\n\n\t\tprivate @Nullable Object getFieldValue(Object instance, String fieldName) {\n\t\t\t@Nullable Field field = ReflectionUtils.findField(instance.getClass(), fieldName);\n\t\t\tif (field == null) {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\tfield.setAccessible(true);\n\t\t\ttry {","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/alibaba/spring-cloud-alibaba/blob/115d5901102009492e05d5ec18c3f79cad4077d0/spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-sentinel/src/main/java/com/alibaba/cloud/sentinel/feign/SentinelFeign.java#L153-L189","documentation":"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.","triggerScenarios":"@FeignClient(fallback = WrongType.class) where WrongType does not implement the feign interface; a fallbackFactory whose create(...) returns an object of an unrelated type.","commonSituations":"Creating a fallback class and forgetting to 'implements MyFeignClient'. A fallbackFactory returning a generic Object or a map-based proxy that lacks the interface.","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."],"exampleFix":"// before\npublic class MyApiFallback { public Result foo() { ... } }\n// after\npublic class MyApiFallback implements MyApi { @Override public Result foo() { ... } }","handlingStrategy":"type-guard","validationCode":"void assertFallbackAssignable(Class<?> fallbackType, Class<?> feignInterface) {\n  if (!feignInterface.isAssignableFrom(fallbackType))\n    throw new IllegalStateException(fallbackType + \" is not a \" + feignInterface);\n}","typeGuard":"static boolean fallbackMatches(Class<?> fallbackType, Class<?> feignInterface) {\n  return feignInterface.isAssignableFrom(fallbackType);\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["sentinel","feign","fallback","type-mismatch"],"backgroundTag":null,"analyzedSha":"115d5901102009492e05d5ec18c3f79cad4077d0","analyzedAt":"2026-08-14T04:47:13.900Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}