alibaba/spring-cloud-alibaba · error · IllegalStateException

Fallback method not found for method: {method}

Error message

Fallback method not found for method: {method}

What it means

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.

Source

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

			else {
				String resourceName = methodMetadata.template().method().toUpperCase(Locale.ROOT)
						+ ":" + hardCodedTarget.url() + methodMetadata.template().path();
				Entry entry = null;
				try {
					ContextUtil.enter(resourceName);
					entry = SphU.entry(resourceName, EntryType.OUT, 1, args);
					result = methodHandler.invoke(args);
				}
				catch (Throwable ex) {
					// fallback handle
					if (!BlockException.isBlockException(ex)) {
						Tracer.traceEntry(ex, entry);
					}
					if (fallbackFactory != null && fallbackMethodMap != null) {
						try {
							Method fallbackMethod = fallbackMethodMap.get(method);
							if (fallbackMethod == null) {
								throw new IllegalStateException("Fallback method not found for method: " + method);
							}
							Object fallbackResult = fallbackMethod.invoke(fallbackFactory.create(ex), args);
							return fallbackResult;
						}
						catch (IllegalAccessException e) {
							// shouldn't happen as method is public due to being an
							// interface
							throw new AssertionError(e);
						}
						catch (InvocationTargetException e) {
							throw e.getCause();
						}
					}
					else {
						// throw exception if fallbackFactory is null
						throw ex;
					}
				}

View on GitHub (pinned to 115d590110)

Solutions

1. Ensure the fallback class/factory declares a matching method for every feign interface method (same name and compatible signature).
2. Regenerate generated fallback classes after changing the feign interface.
3. If using a fallbackFactory.create(ex) proxy, make sure it implements the full interface.
4. Add a unit test that reflects over the interface and asserts each method has a fallback counterpart.

Example fix

// before: interface has bar() but fallback does not
public interface MyApi { Result foo(); Result bar(); }
public class MyApiFallback implements MyApi { public Result foo() { ... } }
// after
public class MyApiFallback implements MyApi { public Result foo() { ... } public Result bar() { ... } }

void assertFallbackCovers(Class<?> feignInterface, Class<?> fallbackType) {
  for (java.lang.reflect.Method m : feignInterface.getMethods()) {
    if (m.isDefault()) continue;
    try { fallbackType.getMethod(m.getName(), m.getParameterTypes()); }
    catch (NoSuchMethodException e) { throw new IllegalStateException("Fallback missing " + m); }
  }
}

static boolean fallbackCovers(Class<?> feignInterface, Class<?> fallbackType) {
  for (java.lang.reflect.Method m : feignInterface.getMethods()) {
    if (m.isDefault()) continue;
    try { fallbackType.getMethod(m.getName(), m.getParameterTypes()); }
    catch (NoSuchMethodException e) { return false; }
  }
  return true;
}

try { api.call(); }
catch (IllegalStateException e) { if (e.getMessage().contains("Fallback method not found")) { /* log and rethrow original */ } else throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• FeignClientFactoryBean not found for {targetType}
• FeignClientFactory not initialized
• No %s instance of type %s found for feign client %s
• {type} create fail
• {type} FactoryBean returned null

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