alibaba/nacos · error · NacosRuntimeException

500

500

Error message

this class name not found

What it means

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.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/utils/ClassUtils.java:154

     * Register the given common classes with the ClassUtils cache.
     */
    private static void registerCommonClasses(Class<?>... commonClasses) {
        for (Class<?> clazz : commonClasses) {
            COMMON_CLASS_CACHE.put(clazz.getName(), clazz);
        }
    }
    
    /**
     * Finds and returns class by className.
     *
     * @param className String value for className.
     * @return class Instances of the class represent classes and interfaces.
     */
    public static Class findClassByName(String className) {
        try {
            return Class.forName(className);
        } catch (Exception e) {
            throw new NacosRuntimeException(SERVER_ERROR, "this class name not found");
        }
    }
    
    /**
     * Determines if the class or interface represented by this object is either the same as, or is a superclass or
     * superinterface of, the class or interface represented by the specified parameter.
     *
     * @param clazz Instances of the class represent classes and interfaces.
     * @param cls   Instances of the class represent classes and interfaces.
     * @return the value indicating whether objects of the type can be assigned to objects of this class.
     */
    public static boolean isAssignableFrom(Class clazz, Class cls) {
        Objects.requireNonNull(cls, "cls");
        return clazz.isAssignableFrom(cls);
    }
    
    /**
     * Gets and returns the class name.

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Find which config key references the class (search application config and the stack frames above findClassByName).
2. Add the missing jar to the classpath, or correct the FQN typo in configuration.
3. After fixing, restart and confirm the SPI/plugin initializes without the error.

// Verify the class is loadable before SPI instantiation.
try {
    Class.forName(className);
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("Configured class not on classpath: " + className, e);
}

try {
    Class<?> clazz = ClassUtils.findClassByName(className);
} catch (NacosRuntimeException e) {
    if ("this class name not found".equals(e.getMessage())) {
        throw new IllegalArgumentException("Missing class for SPI/plugin: " + className, e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• -400
• 500
• DATA_ACCESS_ERROR
• RESOURCE_NOT_FOUND
• PARAMETER_VALIDATE_ERROR

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/77f9859c314930c3. Report an issue: GitHub.