apache/dubbo · error · IllegalStateException

Not unique method for method name(%s) in class(%s), find %d

Error message

Not unique method for method name(%s) in class(%s), find %d methods.

What it means

When ReflectUtils.findMethodByMethodSignature is called with parameterTypes=null (meaning 'search by name only') and more than one public method shares that name (overloads), it cannot unambiguously select one. It throws IllegalStateException with a formatted message naming the method, class, and the count of matches found. The caller must disambiguate by specifying parameter types.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/utils/ReflectUtils.java:914

    @Deprecated
    public static Method findMethodByMethodSignature(Class<?> clazz, String methodName, String[] parameterTypes)
            throws NoSuchMethodException, ClassNotFoundException {
        Method method;
        if (parameterTypes == null) {
            List<Method> found = new ArrayList<>();
            for (Method m : clazz.getMethods()) {
                if (m.getName().equals(methodName)) {
                    found.add(m);
                }
            }
            if (found.isEmpty()) {
                throw new NoSuchMethodException("No such method " + methodName + " in class " + clazz);
            }
            if (found.size() > 1) {
                String msg = String.format(
                        "Not unique method for method name(%s) in class(%s), find %d methods.",
                        methodName, clazz.getName(), found.size());
                throw new IllegalStateException(msg);
            }
            method = found.get(0);
        } else {
            Class<?>[] types = new Class<?>[parameterTypes.length];
            for (int i = 0; i < parameterTypes.length; i++) {
                types[i] = ReflectUtils.name2class(parameterTypes[i]);
            }
            method = clazz.getMethod(methodName, types);
        }
        return method;
    }

    /**
     * @param clazz      Target class to find method
     * @param methodName Method signature, e.g.: method1(int, String). It is allowed to provide method name only, e.g.: method2
     * @return target method
     * @throws NoSuchMethodException
     * @throws ClassNotFoundException

View on GitHub (pinned to 3a3043227f)

Solutions

Pass a non-null parameterTypes array to findMethodByMethodSignature to disambiguate the overload.
Alternatively, use clazz.getMethod(methodName, paramTypes...) directly for a precise lookup.
If using generic invocation ($invoke), always supply the parameter type strings alongside the arguments.
Consider renaming overloaded methods to unique names if the calling code cannot easily provide parameter types.

Example fix

// before — ambiguous overload
Method m = ReflectUtils.findMethodByMethodSignature(
    MyService.class, "doSomething", null); // 2 overloads found
// after — specify parameter types
Method m = ReflectUtils.findMethodByMethodSignature(
    MyService.class, "doSomething",
    new String[]{"java.lang.String"});

Defensive patterns

Strategy: validation

Validate before calling

// Check for overloaded methods and require parameter types if ambiguous
long overloadCount = Arrays.stream(clazz.getMethods())
    .filter(m -> m.getName().equals(methodName))
    .count();
if (overloadCount > 1 && parameterTypes == null) {
    throw new IllegalStateException(
        "Method '" + methodName + "' has " + overloadCount
        + " overloads on " + clazz.getName()
        + ". Provide parameterTypes to disambiguate.");
}
ReflectUtils.findMethodByMethodSignature(clazz, methodName, parameterTypes);

Try / catch

try {
    return ReflectUtils.findMethodByMethodSignature(clazz, methodName, paramTypes);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Not unique method")) {
        // Disambiguate by providing parameter types from method signature
        throw new IllegalArgumentException(
            "Ambiguous method. Provide parameterTypes array.", e);
    }
    throw e;
}

Prevention

Always pass parameter types when looking up methods that may be overloaded.
Avoid overloaded method names in Dubbo service interfaces — use distinct names instead.
In generic invocation ($invoke), always supply the parameterTypes[] argument alongside args.

When it happens

Trigger: Calling ReflectUtils.findMethodByMethodSignature(clazz, methodName, null) where clazz has multiple overloaded methods with the same name — e.g. 'doSomething(String)' and 'doSomething(String, int)'. Without parameter type information, the method cannot determine which overload to return.

Common situations: A service interface with overloaded method names, and a generic/dynamic invocation path that looks up methods by name only. The fix is always to provide the parameter type array so the lookup is unambiguous. This can also occur in Dubbo's internal method resolution for generic invocation ($invoke) when the caller doesn't supply parameter types.

Related errors

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/9b20eb9204ef02d5. Report an issue: GitHub.