alibaba/nacos · error · IllegalArgumentException

Plugin config key requires restart and cannot be updated at

Error message

Plugin config key requires restart and cannot be updated at runtime: {}

What it means

Error "Plugin config key requires restart and cannot be updated at runtime: {}" thrown in alibaba/nacos.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/plugin/config/PluginConfigBasicChecker.java:125

            }
        }
    }
    
    private void validateRuntimeChangedKeys(Map<String, String> currentConfig,
        Map<String, String> newConfig, Map<String, ConfigItemDefinition> definitions) {
        Map<String, String> current = currentConfig == null ? Collections.emptyMap()
            : currentConfig;
        Set<String> changedKeys = new LinkedHashSet<>(current.keySet());
        changedKeys.addAll(newConfig.keySet());
        for (String key : changedKeys) {
            if (Objects.equals(current.get(key), newConfig.get(key))
                && current.containsKey(key) == newConfig.containsKey(key)) {
                continue;
            }
            ConfigItemDefinition definition = definitions.get(key);
            if (definition != null
                && ConfigItemEffectMode.RUNTIME != definition.getEffectMode()) {
                throw new IllegalArgumentException("Plugin config key requires restart and cannot "
                    + "be updated at runtime: " + key);
            }
        }
    }
    
    private void validateConfigValues(Map<String, String> config,
        Map<String, ConfigItemDefinition> definitions) {
        for (Map.Entry<String, String> entry : config.entrySet()) {
            validateValueType(definitions.get(entry.getKey()), entry.getValue());
        }
    }
    
    private void validateValueType(ConfigItemDefinition definition, String value) {
        ConfigItemType type = definition.getType();
        if (type == null || ConfigItemType.STRING == type) {
            return;
        }
        switch (type) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Apply the change through the restart-aware configuration path and restart the server.

When it happens

Trigger: Thrown at core/src/main/java/com/alibaba/nacos/core/plugin/config/PluginConfigBasicChecker.java:125 when the library encounters an invalid state.

Common situations: Updating a plugin config key at runtime that requires restart.

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