alibaba/nacos · critical · IllegalStateException

Built-in LDAP auth plugin is not available

Error message

Built-in LDAP auth plugin is not available

What it means

Thrown by LdapPluginConfiguration.getLdapAuthPluginService() when the registered AuthPluginService for the LDAP auth type is not an instance of LdapAuthPluginService. This indicates the built-in LDAP plugin failed to load or register correctly, so the type check fails and an IllegalStateException is thrown. Unlike MissingLdapAuthenticationManager (which starts the server but fails auth), this is a startup/wiring failure.

Source

Thrown at plugin-default-impl/nacos-ldap-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/ldap/LdapPluginConfiguration.java:88

    }
    
    @Bean
    public GlobalAuthenticationConfigurerAdapter authenticationConfigurer(
        LdapAuthenticationProvider ldapAuthenticationProvider) {
        return new GlobalAuthenticationConfigurerAdapter() {
            
            @Override
            public void init(AuthenticationManagerBuilder auth) {
                auth.authenticationProvider(ldapAuthenticationProvider);
            }
        };
    }
    
    static LdapAuthPluginService getLdapAuthPluginService() {
        AuthPluginService plugin = AuthPluginManager.getInstance().getAllPlugins()
            .get(AuthConstants.LDAP_AUTH_PLUGIN_TYPE);
        if (!(plugin instanceof LdapAuthPluginService)) {
            throw new IllegalStateException("Built-in LDAP auth plugin is not available");
        }
        return (LdapAuthPluginService) plugin;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify the nacos-ldap-auth-plugin jar is present and intact in the classpath/plugins directory.
2. Check startup logs for an SPI load failure or exception during LDAP plugin initialization.
3. Ensure no other plugin is shadowing the LDAP_AUTH_PLUGIN_TYPE identifier.
4. Confirm the LdapAuthPluginService interface and its implementation come from the same classloader (no shaded-duplicate conflict).

try {
    LdapAuthPluginService service = LdapPluginConfiguration.getLdapAuthPluginService();
} catch (IllegalStateException e) {
    // plugin failed to load; check SPI jar and startup logs
}

When it happens

Trigger: getLdapAuthPluginService() is called during Spring configuration wiring; AuthPluginManager.getAllPlugins().get(LDAP_AUTH_PLUGIN_TYPE) returns null or a non-LdapAuthPluginService instance, failing the instanceof check at line 88.

Common situations: The LDAP auth plugin SPI jar is missing or corrupted so it never registered; a conflicting custom plugin claims the LDAP type name; the plugin threw during initialization and registered a broken instance; classpath shading split the LdapAuthPluginService interface from its impl.

Related errors

• LDAP auth plugin requires org.springframework.ldap:spring-ld
• user not found!
• LDAP login failed.
• user not found
• Plugin config value cannot be null: {key}

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