alibaba/nacos · warning · IllegalArgumentException

Pre-context plugin {} requires restart: {pluginId}

Error message

Pre-context plugin {} requires restart: {pluginId}

What it means

validateRuntimeChangeSupported throws IllegalArgumentException (mapped by setPluginEnabled / updatePluginConfig to HTTP 400 / PARAMETER_VALIDATE_ERROR 20002) for plugins whose initialization phase is PRE_CONTEXT — plugins initialized before the Spring context is ready (e.g. environment / early-bootstrap auth plugins). Their state and config are fixed for the process lifetime.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/plugin/PluginManager.java:872

            return false;
        }
        PluginInfo pluginInfo = pluginRegistry.get(pluginId);
        if (pluginInfo != null) {
            return isPreContextPlugin(pluginInfo);
        }
        int separator = pluginId.indexOf(':');
        String typeName = separator < 0 ? pluginId : pluginId.substring(0, separator);
        for (PluginType type : PluginType.values()) {
            if (type.getType().equals(typeName)) {
                return PluginInitializationPhase.PRE_CONTEXT == type.getInitializationPhase();
            }
        }
        return false;
    }
    
    private void validateRuntimeChangeSupported(PluginInfo pluginInfo, String operation) {
        if (isPreContextPlugin(pluginInfo)) {
            throw new IllegalArgumentException("Pre-context plugin " + operation
                + " requires restart: " + pluginInfo.getPluginId());
        }
    }
    
    private PluginStateSynchronizer getClusterSynchronizer() throws NacosApiException {
        if (synchronizer == null) {
            throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,
                "Plugin state synchronizer is unavailable in cluster mode");
        }
        return synchronizer;
    }
    
    private void applyStandaloneStateChange(String pluginId, boolean enabled)
        throws NacosApiException {
        try {
            persistence.saveState(pluginId, enabled);
            applyStateChange(pluginId, enabled);
        } catch (IllegalArgumentException e) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Do not attempt runtime state/config changes on pre-context plugins.
2. Change the relevant startup configuration / property and restart the server.
3. Identify pre-context plugins from the error (type name) and treat them as restart-only.

Example fix

// before
PUT /v3/console/plugin/status?pluginType=environment&pluginName=...&enabled=false
// after: configure at startup and restart
# application.properties / JVM args, then restart the server

// Pre-context plugins cannot change at runtime; detect by type and reject early
if (isPreContextType(pluginType)) {  // mirror server's PluginType phase check
    throw new IllegalStateException(pluginType + " is pre-context; configure at startup and restart");
}

try {
    pluginClient.setEnabled(type, name, enabled, localOnly);
} catch (NacosApiException e) {
    if (e.getErrCode() == 20002 && e.getMessage().contains("requires restart")) {
        // guide user to startup config + restart
    } else { throw e; }
}

When it happens

Trigger: Calling PUT /v3/console/plugin/status or PUT /v3/console/plugin/config on a pre-context plugin (its type name maps to a PluginType with initialization phase PRE_CONTEXT).

Common situations: Trying to disable or reconfigure an environment/bootstrap plugin live; not realizing some plugins must be set before startup.

Related errors

• Plugin selection for exclusive type '{}' requires restart. U
• baseType must not be null
• subtype must not be null
• typeName must not be empty
• PARAMETER_VALIDATE_ERROR

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