OpenFeign/feign · error · IllegalStateException

is not a method handled by feign

Error message

${configKey} is not a method handled by feign

What it means

A generic guard inside createMethodHandler: when the MethodMetadata for a method is flagged isIgnored, Feign installs a handler that always throws this IllegalStateException. It fires at invocation time if application code calls an interface method that Feign deliberately excludes from handling (via ignoreMethods/ignored method configuration), meaning the proxy cannot produce a request for it.

Solutions

1. Remove the method from Feign's ignored-methods configuration so it gets a real handler
2. Change client code to not call that method through the Feign proxy
3. If the method should not be remote, implement it locally (default method or separate class)
4. Confirm the configKey in the error matches the method you intended to configure

When it happens

Trigger: Thrown at core/src/main/java/feign/ReflectiveFeign.java:223 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/cf6515c0c26ec3f9. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/feign/ReflectiveFeign.java:223

    private static boolean isMoreSpecific(Method candidate, Method current) {
      Class<?>[] candidateParams = candidate.getParameterTypes();
      Class<?>[] currentParams = current.getParameterTypes();
      for (int i = 0; i < candidateParams.length; i++) {
        if (candidateParams[i] != currentParams[i]
            && currentParams[i].isAssignableFrom(candidateParams[i])) {
          return true;
        }
      }
      Class<?> candidateReturn = candidate.getReturnType();
      Class<?> currentReturn = current.getReturnType();
      return candidateReturn != currentReturn && currentReturn.isAssignableFrom(candidateReturn);
    }

    private MethodHandler createMethodHandler(
        final Target<?> target, final MethodMetadata md, final C requestContext) {
      if (md.isIgnored()) {
        return args -> {
          throw new IllegalStateException(md.configKey() + " is not a method handled by feign");
        };
      }

      return factory.create(target, md, requestContext);
    }
  }

  private static class TargetSpecificationVerifier {
    public static <T> void verify(Target<T> target) {
      Class<T> type = target.type();
      if (!type.isInterface()) {
        throw new IllegalArgumentException("Type must be an interface: " + type);
      }

      for (final Method m : type.getMethods()) {
        final Class<?> retType = m.getReturnType();

        if (!CompletableFuture.class.isAssignableFrom(retType)) {

View on GitHub (pinned to e2a1e27560)