{"record":{"id":"77f9859c314930c3","repo":"alibaba/nacos","slug":"500-77f985","errorCode":"500","errorMessage":"this class name not found","messagePattern":"this class name not found","errorType":"exception","errorClass":"NacosRuntimeException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/com/alibaba/nacos/common/utils/ClassUtils.java","lineNumber":154,"sourceCode":"     * Register the given common classes with the ClassUtils cache.\n     */\n    private static void registerCommonClasses(Class<?>... commonClasses) {\n        for (Class<?> clazz : commonClasses) {\n            COMMON_CLASS_CACHE.put(clazz.getName(), clazz);\n        }\n    }\n    \n    /**\n     * Finds and returns class by className.\n     *\n     * @param className String value for className.\n     * @return class Instances of the class represent classes and interfaces.\n     */\n    public static Class findClassByName(String className) {\n        try {\n            return Class.forName(className);\n        } catch (Exception e) {\n            throw new NacosRuntimeException(SERVER_ERROR, \"this class name not found\");\n        }\n    }\n    \n    /**\n     * Determines if the class or interface represented by this object is either the same as, or is a superclass or\n     * superinterface of, the class or interface represented by the specified parameter.\n     *\n     * @param clazz Instances of the class represent classes and interfaces.\n     * @param cls   Instances of the class represent classes and interfaces.\n     * @return the value indicating whether objects of the type can be assigned to objects of this class.\n     */\n    public static boolean isAssignableFrom(Class clazz, Class cls) {\n        Objects.requireNonNull(cls, \"cls\");\n        return clazz.isAssignableFrom(cls);\n    }\n    \n    /**\n     * Gets and returns the class name.","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/common/src/main/java/com/alibaba/nacos/common/utils/ClassUtils.java#L136-L172","documentation":"Thrown by ClassUtils.findClassByName(String) when Class.forName(className) throws any exception. It is a NacosRuntimeException with SERVER_ERROR (500) and a generic 'this class name not found' message — note the original exception and class name are swallowed, which makes diagnosis harder. This helper is used by the SPI/plugin loader to instantiate configurable classes by fully-qualified name.","triggerScenarios":"Nacos configuration references a class by FQN (e.g., a datasource plugin, auth plugin, trace plugin, or executor type) that is not on the classpath. Typical entry points: spi loading, datasource dialect selection, encryption/auth/trace plugin configuration.","commonSituations":"Configuring a plugin class whose jar is missing from the deployment; a typo in the class name in application.properties/nacos-server config; upgrading Nacos and a renamed/removed class is still referenced; fat-jar shading that excluded the class.","solutions":["Find which config key references the class (search application config and the stack frames above findClassByName).","Add the missing jar to the classpath, or correct the FQN typo in configuration.","After fixing, restart and confirm the SPI/plugin initializes without the error."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Verify the class is loadable before SPI instantiation.\ntry {\n    Class.forName(className);\n} catch (ClassNotFoundException e) {\n    throw new IllegalArgumentException(\"Configured class not on classpath: \" + className, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Class<?> clazz = ClassUtils.findClassByName(className);\n} catch (NacosRuntimeException e) {\n    if (\"this class name not found\".equals(e.getMessage())) {\n        throw new IllegalArgumentException(\"Missing class for SPI/plugin: \" + className, e);\n    }\n    throw e;\n}","preventionTips":["Validate plugin/SPI class names at startup and fail fast with the class name in the message.","Keep deployment jars and configuration in sync.","Double-check FQNs for typos when copying class names into config."],"tags":["spi","classpath","plugin-loading","configuration","reflection"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}