{"record":{"id":"07e8af10016cd8c7","repo":"alibaba/nacos","slug":"pre-context-plugin-requires-restart-pluginid","errorCode":null,"errorMessage":"Pre-context plugin {} requires restart: {pluginId}","messagePattern":"Pre-context plugin (.+?) requires restart: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"warning","filePath":"core/src/main/java/com/alibaba/nacos/core/plugin/PluginManager.java","lineNumber":872,"sourceCode":"            return false;\n        }\n        PluginInfo pluginInfo = pluginRegistry.get(pluginId);\n        if (pluginInfo != null) {\n            return isPreContextPlugin(pluginInfo);\n        }\n        int separator = pluginId.indexOf(':');\n        String typeName = separator < 0 ? pluginId : pluginId.substring(0, separator);\n        for (PluginType type : PluginType.values()) {\n            if (type.getType().equals(typeName)) {\n                return PluginInitializationPhase.PRE_CONTEXT == type.getInitializationPhase();\n            }\n        }\n        return false;\n    }\n    \n    private void validateRuntimeChangeSupported(PluginInfo pluginInfo, String operation) {\n        if (isPreContextPlugin(pluginInfo)) {\n            throw new IllegalArgumentException(\"Pre-context plugin \" + operation\n                + \" requires restart: \" + pluginInfo.getPluginId());\n        }\n    }\n    \n    private PluginStateSynchronizer getClusterSynchronizer() throws NacosApiException {\n        if (synchronizer == null) {\n            throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,\n                \"Plugin state synchronizer is unavailable in cluster mode\");\n        }\n        return synchronizer;\n    }\n    \n    private void applyStandaloneStateChange(String pluginId, boolean enabled)\n        throws NacosApiException {\n        try {\n            persistence.saveState(pluginId, enabled);\n            applyStateChange(pluginId, enabled);\n        } catch (IllegalArgumentException e) {","sourceCodeStart":854,"sourceCodeEnd":890,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/core/src/main/java/com/alibaba/nacos/core/plugin/PluginManager.java#L854-L890","documentation":"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.","triggerScenarios":"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).","commonSituations":"Trying to disable or reconfigure an environment/bootstrap plugin live; not realizing some plugins must be set before startup.","solutions":["Do not attempt runtime state/config changes on pre-context plugins.","Change the relevant startup configuration / property and restart the server.","Identify pre-context plugins from the error (type name) and treat them as restart-only."],"exampleFix":"// before\nPUT /v3/console/plugin/status?pluginType=environment&pluginName=...&enabled=false\n// after: configure at startup and restart\n# application.properties / JVM args, then restart the server","handlingStrategy":"validation","validationCode":"// Pre-context plugins cannot change at runtime; detect by type and reject early\nif (isPreContextType(pluginType)) {  // mirror server's PluginType phase check\n    throw new IllegalStateException(pluginType + \" is pre-context; configure at startup and restart\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    pluginClient.setEnabled(type, name, enabled, localOnly);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == 20002 && e.getMessage().contains(\"requires restart\")) {\n        // guide user to startup config + restart\n    } else { throw e; }\n}","preventionTips":["Treat environment/bootstrap plugins as restart-only.","Set pre-context plugin config before server start.","Recognize pre-context types from the error message."],"tags":["plugin","pre-context","restart-required","validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}