apache/dubbo · error · IllegalStateException

Not found class ${name}, cause: ${e.getMessage()}

Error message

Not found class ${name}, cause: ${e.getMessage()}

What it means

ReflectUtils.forName(String name) converts a fully-qualified class name (or primitive keyword) to a Class object via name2class. If the class is not found on the classpath (ClassNotFoundException), it is wrapped in an IllegalStateException with a descriptive message including the class name and the original cause. This is the standard class-loading failure path.

Source

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

                    break;
                }
                default:
                    throw new RuntimeException();
            }
        } else {
            sb.append(desc.substring(c + 1, desc.length() - 1).replace('/', '.'));
        }
        while (c-- > 0) {
            sb.append("[]");
        }
        return sb.toString();
    }

    public static Class<?> forName(String name) {
        try {
            return name2class(name);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("Not found class " + name + ", cause: " + e.getMessage(), e);
        }
    }

    public static Class<?> forName(ClassLoader cl, String name) {
        try {
            return name2class(cl, name);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("Not found class " + name + ", cause: " + e.getMessage(), e);
        }
    }

    /**
     * name to class.
     * "boolean" => boolean.class
     * "java.util.Map[][]" => java.util.Map[][].class
     *
     * @param name name.
     * @return Class instance.

View on GitHub (pinned to 3a3043227f)

Solutions

1. Ensure the JAR containing the named class is on the classpath of both consumer and provider.
2. Check for typo or version mismatch in the class name — the exception message shows the exact name being resolved.
3. Verify the thread context classloader can see the class (in app servers, ensure the classloader hierarchy is correct).
4. If using shaded/relocated JARs, verify the package name matches the actual relocated package.

Example fix

// before — missing dependency
ReflectUtils.forName("com.example.NewService"); // ClassNotFoundException
// after — add the correct dependency/class
ReflectUtils.forName("com.example.OldService"); // correct name
// or add JAR to pom.xml

// Verify class exists before calling forName
try {
    Class.forName(name, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("Class not on classpath: " + name
        + ". Add the required dependency.", e);
}

try {
    return ReflectUtils.forName(name);
} catch (IllegalStateException e) {
    if (e.getCause() instanceof ClassNotFoundException) {
        logger.error("Class {} not found. Check classpath and dependencies.", name);
    }
    throw e;
}

When it happens

Trigger: Calling ReflectUtils.forName("com.example.MissingClass") where the named class is not present in the current thread's context classloader. Internally name2class resolves primitive names and array notation, then calls Class.forName via the context classloader.

Common situations: A Dubbo service interface class or a serialized object's class is referenced in a consumer or provider that does not have the dependency on its classpath. Common with missing JARs, version mismatches where a class was renamed or removed, or classloader isolation issues (e.g. in OSGi or app servers where the interface JAR is not exported).

Related errors

• Method [{}] not found.
• Class not found: ${desc}
• Can not merge result because missing method [ {merger} ] in
• Can not merge result: {e.getMessage()}
• unable to determine bean class from factory's superclass or

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