alibaba/nacos · critical · AccessException

LDAP auth plugin requires org.springframework.ldap:spring-ld

Error message

LDAP auth plugin requires org.springframework.ldap:spring-ldap-core in plugins/classpath when nacos.plugin.auth.type=ldap (legacy alias: nacos.core.auth.system.type=ldap). Please add spring-ldap-core jar into the plugins directory.

What it means

Thrown by MissingLdapAuthenticationManager.authenticate(username, rawPassword) — a stub implementation of IAuthenticationManager used when the LDAP auth plugin is selected (nacos.plugin.auth.type=ldap) but the required spring-ldap-core jar is absent from the plugins classpath. Every method on this stub throws AccessException with a descriptive configuration message so the server starts but login fails loudly rather than with a cryptic ClassNotFoundException.

Source

Thrown at plugin-default-impl/nacos-ldap-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/authenticate/MissingLdapAuthenticationManager.java:39

import com.alibaba.nacos.plugin.auth.impl.users.NacosUser;
import jakarta.servlet.http.HttpServletRequest;

/**
 * Fallback authentication manager for missing LDAP runtime dependency.
 *
 * @author xiweng.yy
 */
public class MissingLdapAuthenticationManager implements IAuthenticationManager {
    
    private final String message;
    
    public MissingLdapAuthenticationManager(String message) {
        this.message = message;
    }
    
    @Override
    public NacosUser authenticate(String username, String rawPassword) throws AccessException {
        throw new AccessException(message);
    }
    
    @Override
    public NacosUser authenticate(String jwtToken) throws AccessException {
        throw new AccessException(message);
    }
    
    @Override
    public NacosUser authenticate(HttpServletRequest httpServletRequest) throws AccessException {
        throw new AccessException(message);
    }
    
    @Override
    public void authorize(Permission permission, NacosUser nacosUser) throws AccessException {
        throw new AccessException(message);
    }
    
    @Override

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Download org.springframework.ldap:spring-ldap-core and place the jar in the Nacos plugins directory (typically plugins/ or the configured plugins.classpath).
2. Restart the Nacos server after adding the jar so it is loaded on the plugin classpath.
3. Verify the jar version is compatible with the Nacos LDAP auth plugin version.

Example fix

# before: plugins dir has no spring-ldap-core
# after: copy the jar into plugins/
cp spring-ldap-core-<version>.jar /path/to/nacos/plugins/
# then restart Nacos

// Before starting the server, verify the jar is present
// java code to check classpath at startup:
try {
    Class.forName("org.springframework.ldap.core.LdapTemplate");
} catch (ClassNotFoundException e) {
    // spring-ldap-core missing; do not enable LDAP auth
}

static boolean isLdapCoreAvailable() {
    try {
        Class.forName("org.springframework.ldap.core.LdapTemplate");
        return true;
    } catch (ClassNotFoundException e) {
        return false;
    }
}

try {
    NacosUser user = ldapAuthManager.authenticate(username, rawPassword);
} catch (AccessException e) {
    if (e.getMessage().contains("spring-ldap-core")) {
        // stop attempting logins; fix the plugins directory and restart
    }
}

When it happens

Trigger: Server is configured with nacos.plugin.auth.type=ldap (or legacy nacos.core.auth.system.type=ldap) but the plugins directory does not contain org.springframework.ldap:spring-ldap-core. Any authentication call (username/password, JWT, or HttpServletRequest) routes to this stub and throws.

Common situations: After enabling LDAP auth, the deployer forgot to copy the spring-ldap-core jar into the Nacos plugins folder; or an upgrade changed the expected plugin directory layout.

Related errors

• LDAP login failed.
• Plugin config value cannot be null: {key}
• Plugin config value must be positive: {key}
• Plugin config value is not a number: {key}
• Plugin config value is not a boolean: {key}

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