alibaba/nacos · critical · IllegalStateException

Built-in OIDC auth plugin is not available

Error message

Built-in OIDC auth plugin is not available

What it means

Thrown at Spring bean wiring time by OidcPluginAutoConfiguration.getOidcAuthPluginService() when the AuthPluginManager registry does not contain an OidcAuthPluginService instance under the OIDC auth type. This is a startup/SPI wiring failure: OIDC auth was enabled (ConditionOnOidcAuth matched) but the plugin was never loaded or is the wrong type.

Source

Thrown at plugin-default-impl/nacos-oidc-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/oidc/config/OidcPluginAutoConfiguration.java:56

@Import(OidcWebSecurityConfig.class)
@SuppressWarnings("PMD")
public class OidcPluginAutoConfiguration {
    
    /**
     * Register OidcLoginController bean.
     *
     * @return OidcLoginController
     */
    @Bean
    public OidcLoginController oidcLoginController() {
        return new OidcLoginController(getOidcAuthPluginService());
    }
    
    static OidcAuthPluginService getOidcAuthPluginService() {
        AuthPluginService plugin = AuthPluginManager.getInstance().getAllPlugins()
            .get(OidcProtocolConstants.AUTH_PLUGIN_TYPE);
        if (!(plugin instanceof OidcAuthPluginService)) {
            throw new IllegalStateException("Built-in OIDC auth plugin is not available");
        }
        return (OidcAuthPluginService) plugin;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure plugin-default-impl/nacos-oidc-auth-plugin is packaged and present on the server classpath.
2. Verify the SPI registration file META-INF/services/com.alibaba.nacos.plugin.auth.spi.server.AuthPluginService exists in the jar and names the OIDC service.
3. Check startup logs for an earlier exception during AuthPluginManager initialization that prevented registration.
4. Confirm no conflicting plugin is registering a different type under OidcProtocolConstants.AUTH_PLUGIN_TYPE.

// At startup, verify the OIDC plugin is registered before relying on it
AuthPluginService plugin = AuthPluginManager.getInstance()
    .getAllPlugins().get(OidcProtocolConstants.AUTH_PLUGIN_TYPE);
if (!(plugin instanceof OidcAuthPluginService)) {
    throw new IllegalStateException(
        "OIDC plugin not loaded; check classpath and SPI registration");
}

boolean isOidcPluginLoaded(AuthPluginService p) {
    return p instanceof OidcAuthPluginService;
}

try {
    OidcPluginAutoConfiguration.getOidcAuthPluginService();
} catch (IllegalStateException e) {
    // startup wiring failure — fail fast and report missing jar/SPI
    log.error("OIDC plugin unavailable; ensure nacos-oidc-auth-plugin is on the classpath");
    throw e;
}

When it happens

Trigger: OidcPluginAutoConfiguration is active (OIDC enabled) but AuthPluginManager.getAllPlugins().get(AUTH_PLUGIN_TYPE) returns null or a non-OidcAuthPluginService object. This happens when the SPI service file is missing, the jar is absent, or plugin initialization failed silently.

Common situations: The nacos-oidc-auth-plugin jar is not on the classpath; the META-INF/services AuthPluginService SPI file is missing or doesn't list OidcAuthPluginService; an earlier exception during plugin init left it unregistered; a conflicting custom plugin registered under the same type.

Related errors

• Built-in LDAP auth plugin is not available
• DATA_ACCESS_ERROR
• RESOURCE_NOT_FOUND
• 500
• PARAMETER_VALIDATE_ERROR

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