{"record":{"id":"490a8ac45b2f862b","repo":"alibaba/spring-cloud-alibaba","slug":"fallback-method-not-found-for-method-method","errorCode":null,"errorMessage":"Fallback method not found for method: {method}","messagePattern":"Fallback method not found for method: (.+?)","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/SentinelInvocationHandler.java","lineNumber":127,"sourceCode":"\t\t\telse {\n\t\t\t\tString resourceName = methodMetadata.template().method().toUpperCase(Locale.ROOT)\n\t\t\t\t\t\t+ \":\" + hardCodedTarget.url() + methodMetadata.template().path();\n\t\t\t\tEntry entry = null;\n\t\t\t\ttry {\n\t\t\t\t\tContextUtil.enter(resourceName);\n\t\t\t\t\tentry = SphU.entry(resourceName, EntryType.OUT, 1, args);\n\t\t\t\t\tresult = methodHandler.invoke(args);\n\t\t\t\t}\n\t\t\t\tcatch (Throwable ex) {\n\t\t\t\t\t// fallback handle\n\t\t\t\t\tif (!BlockException.isBlockException(ex)) {\n\t\t\t\t\t\tTracer.traceEntry(ex, entry);\n\t\t\t\t\t}\n\t\t\t\t\tif (fallbackFactory != null && fallbackMethodMap != null) {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tMethod fallbackMethod = fallbackMethodMap.get(method);\n\t\t\t\t\t\t\tif (fallbackMethod == null) {\n\t\t\t\t\t\t\t\tthrow new IllegalStateException(\"Fallback method not found for method: \" + method);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tObject fallbackResult = fallbackMethod.invoke(fallbackFactory.create(ex), args);\n\t\t\t\t\t\t\treturn fallbackResult;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcatch (IllegalAccessException e) {\n\t\t\t\t\t\t\t// shouldn't happen as method is public due to being an\n\t\t\t\t\t\t\t// interface\n\t\t\t\t\t\t\tthrow new AssertionError(e);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcatch (InvocationTargetException e) {\n\t\t\t\t\t\t\tthrow e.getCause();\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\telse {\n\t\t\t\t\t\t// throw exception if fallbackFactory is null\n\t\t\t\t\t\tthrow ex;\n\t\t\t\t\t}\n\t\t\t\t}","sourceCodeStart":109,"sourceCodeEnd":145,"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/SentinelInvocationHandler.java#L109-L145","documentation":"When a feign call is blocked or throws and a fallbackFactory is configured, SentinelInvocationHandler looks up the fallback method for the failed method in fallbackMethodMap. If that map has no entry for the method, this IllegalStateException is thrown instead of recovering, because the handler cannot route the failure. It indicates the fallback method mapping was not built for that method.","triggerScenarios":"Configuring fallbackFactory but the factory's fallback method does not match the signature of the failing feign method, so no mapping is registered. A custom fallbackFactory whose create(...) returns a type without the corresponding method. Calling a method added to the interface after the fallback type was generated.","commonSituations":"Adding a new method to the feign interface and forgetting to add it to the fallback class. A fallbackFactory returning a generic proxy lacking the new method. Annotation processor that generates fallbacks skipping certain methods.","solutions":["Ensure the fallback class/factory declares a matching method for every feign interface method (same name and compatible signature).","Regenerate generated fallback classes after changing the feign interface.","If using a fallbackFactory.create(ex) proxy, make sure it implements the full interface.","Add a unit test that reflects over the interface and asserts each method has a fallback counterpart."],"exampleFix":"// before: interface has bar() but fallback does not\npublic interface MyApi { Result foo(); Result bar(); }\npublic class MyApiFallback implements MyApi { public Result foo() { ... } }\n// after\npublic class MyApiFallback implements MyApi { public Result foo() { ... } public Result bar() { ... } }","handlingStrategy":"validation","validationCode":"void assertFallbackCovers(Class<?> feignInterface, Class<?> fallbackType) {\n  for (java.lang.reflect.Method m : feignInterface.getMethods()) {\n    if (m.isDefault()) continue;\n    try { fallbackType.getMethod(m.getName(), m.getParameterTypes()); }\n    catch (NoSuchMethodException e) { throw new IllegalStateException(\"Fallback missing \" + m); }\n  }\n}","typeGuard":"static boolean fallbackCovers(Class<?> feignInterface, Class<?> fallbackType) {\n  for (java.lang.reflect.Method m : feignInterface.getMethods()) {\n    if (m.isDefault()) continue;\n    try { fallbackType.getMethod(m.getName(), m.getParameterTypes()); }\n    catch (NoSuchMethodException e) { return false; }\n  }\n  return true;\n}","tryCatchPattern":"try { api.call(); }\ncatch (IllegalStateException e) { if (e.getMessage().contains(\"Fallback method not found\")) { /* log and rethrow original */ } else throw e; }","preventionTips":["Add a fallback method for every interface method.","Regenerate generated fallbacks after interface changes.","Unit-test that every interface method has a fallback counterpart."],"tags":["sentinel","feign","fallback","invocation"],"backgroundTag":null,"analyzedSha":"115d5901102009492e05d5ec18c3f79cad4077d0","analyzedAt":"2026-08-14T04:47:13.900Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}