alibaba/spring-cloud-alibaba · error · IllegalStateException

Method handler not found for method: {method}

Error message

Method handler not found for method: {method}

What it means

SentinelInvocationHandler.invoke() looks up the MethodHandler for the called method in its dispatch map. If the method being invoked is not Object.class identity methods (equals/hashCode/toString) and has no entry in dispatch, this IllegalStateException is thrown at call time. It means the feign contract did not register a handler for that method, typically a default or static method or an unannotated method leaking through the proxy.

Source

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

					return false;
				}
				return equals(otherHandler);
			}
			catch (IllegalArgumentException e) {
				return false;
			}
		}
		else if ("hashCode".equals(method.getName())) {
			return hashCode();
		}
		else if ("toString".equals(method.getName())) {
			return toString();
		}

		Object result;
		MethodHandler methodHandler = this.dispatch.get(method);
		if (methodHandler == null) {
			throw new IllegalStateException("Method handler not found for method: " + method);
		}
		// only handle by HardCodedTarget
		if (target instanceof Target.HardCodedTarget hardCodedTarget) {
			MethodMetadata methodMetadata = SentinelContractHolder.METADATA_MAP
					.get(hardCodedTarget.type().getName()
							+ Feign.configKey(hardCodedTarget.type(), method));
			// resource default is HttpMethod:protocol://url
			if (methodMetadata == null) {
				result = methodHandler.invoke(args);
			}
			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);

View on GitHub (pinned to 115d590110)

Solutions

1. Only call methods that the feign contract maps (annotated interface methods).
2. Move helper/default logic out of the feign interface into a separate service.
3. If using a custom Contract, ensure it registers every callable method.
4. Rebuild the feign client metadata so dispatch is populated for all intended methods.

void assertDispatched(Method m, Map<Method,?> dispatch) {
  if (m.getDeclaringClass() == Object.class) return;
  if (!dispatch.containsKey(m)) throw new IllegalStateException("No handler for " + m);
}

static boolean isHandled(Method m, Map<Method,?> dispatch) {
  return m.getDeclaringClass() == Object.class || dispatch.containsKey(m);
}

try { proxy.callMethod(); }
catch (IllegalStateException e) { if (e.getMessage().contains("handler not found")) { /* route to default impl */ } else throw e; }

When it happens

Trigger: Calling a default method or a method not covered by the feign contract on the proxied interface. Reflectively invoking a method object that is a bridge/synthetic variant not present in dispatch. A contract customization that excludes methods the client still calls.

Common situations: Adding a default helper method to a feign interface and calling it directly. Custom Contract beans that drop some @RequestLine methods. Version skew between the interface and the registered metadata.

Related errors

• Fallback method not found for method: {method}
• ApplicationContext or FeignClientFactory not initialized
• FeignClientFactoryBean not found for {targetType}
• FeignClientFactory not initialized
• No %s instance of type %s found for feign client %s

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