{"record":{"id":"9364c53b93496eb9","repo":"apache/dubbo","slug":"not-found-class-name-cause-e-getmessage","errorCode":null,"errorMessage":"Not found class ${name}, cause: ${e.getMessage()}","messagePattern":"Not found class (.+?), cause: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/utils/ReflectUtils.java","lineNumber":687,"sourceCode":"                    break;\n                }\n                default:\n                    throw new RuntimeException();\n            }\n        } else {\n            sb.append(desc.substring(c + 1, desc.length() - 1).replace('/', '.'));\n        }\n        while (c-- > 0) {\n            sb.append(\"[]\");\n        }\n        return sb.toString();\n    }\n\n    public static Class<?> forName(String name) {\n        try {\n            return name2class(name);\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(\"Not found class \" + name + \", cause: \" + e.getMessage(), e);\n        }\n    }\n\n    public static Class<?> forName(ClassLoader cl, String name) {\n        try {\n            return name2class(cl, name);\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(\"Not found class \" + name + \", cause: \" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * name to class.\n     * \"boolean\" => boolean.class\n     * \"java.util.Map[][]\" => java.util.Map[][].class\n     *\n     * @param name name.\n     * @return Class instance.","sourceCodeStart":669,"sourceCodeEnd":705,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/utils/ReflectUtils.java#L669-L705","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Ensure the JAR containing the named class is on the classpath of both consumer and provider.","Check for typo or version mismatch in the class name — the exception message shows the exact name being resolved.","Verify the thread context classloader can see the class (in app servers, ensure the classloader hierarchy is correct).","If using shaded/relocated JARs, verify the package name matches the actual relocated package."],"exampleFix":"// before — missing dependency\nReflectUtils.forName(\"com.example.NewService\"); // ClassNotFoundException\n// after — add the correct dependency/class\nReflectUtils.forName(\"com.example.OldService\"); // correct name\n// or add JAR to pom.xml","handlingStrategy":"try-catch","validationCode":"// Verify class exists before calling forName\ntry {\n    Class.forName(name, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalArgumentException(\"Class not on classpath: \" + name\n        + \". Add the required dependency.\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return ReflectUtils.forName(name);\n} catch (IllegalStateException e) {\n    if (e.getCause() instanceof ClassNotFoundException) {\n        logger.error(\"Class {} not found. Check classpath and dependencies.\", name);\n    }\n    throw e;\n}","preventionTips":["Ensure shared interface JARs are on both consumer and provider classpaths.","Pin dependency versions to match between consumer and provider builds.","Use a dependency management tool (Maven/Gradle) to detect missing transitive dependencies at build time."],"tags":["reflection","classloading","classpath","class-not-found"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}