alibaba/nacos · error · NacosApiException

SERVER_ERROR

SERVER_ERROR

Error message

Failed to apply local-only plugin config: {pluginId}

What it means

In localOnly mode, PluginManager.updatePluginConfig calls pluginConfigService.updateLocalOnlyConfig; an unexpected RuntimeException (anything other than IllegalArgumentException or PluginConfigApplyException) is wrapped as NacosApiException(SERVER_ERROR 500) with message "Failed to apply local-only plugin config: {pluginId}". The real cause is in the wrapped exception.

Source

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

                e.getMessage());
        }
        
        // LocalOnly mode: only update local memory, skip cluster sync
        if (localOnly) {
            LOGGER.warn(
                "[PluginManager] LocalOnly mode: applying config change to this node only, pluginId={}",
                pluginId);
            try {
                pluginConfigService.updateLocalOnlyConfig(info, pluginInstances.get(pluginId),
                    normalizedConfig);
            } catch (IllegalArgumentException e) {
                throw new NacosApiException(NacosException.INVALID_PARAM,
                    ErrorCode.PARAMETER_VALIDATE_ERROR, e.getMessage());
            } catch (PluginConfigApplyException e) {
                throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR, e,
                    e.getMessage());
            } catch (RuntimeException e) {
                throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR, e,
                    "Failed to apply local-only plugin config: " + pluginId);
            }
            return;
        }
        
        if (EnvUtil.getStandaloneMode()) {
            applyStandaloneConfigChange(pluginId, normalizedConfig);
        } else {
            getClusterSynchronizer().syncConfigChange(pluginId, normalizedConfig);
        }
        
        LOGGER.info("[PluginManager] Plugin {} config updated", pluginId);
    }
    
    /**
     * List all plugins.
     *
     * @return list of plugin info

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Read the server log for the wrapped RuntimeException cause right after this 500.
  2. Fix file permissions / free disk for the plugin state directory.
  3. Correct the config values and retry; if the plugin impl is broken, update/remove the plugin jar.
Defensive patterns

Strategy: try-catch

Validate before calling

// localOnly apply failures are server-side; best you can do is sanity-check config shape
if (config == null || config.isEmpty()) throw new IllegalArgumentException("empty config");

Try / catch

try {
    pluginClient.updateConfig(type, name, config, /*localOnly*/ true);
} catch (NacosApiException e) {
    if (e.getErrCode() == 30000 && e.getMessage().contains("local-only plugin config")) {
        // inspect server log for wrapped cause, fix plugin/permissions, then retry
        log.error("local-only config apply failed for " + type + ":" + name, e);
    } else { throw e; }
}

Prevention

When it happens

Trigger: PUT /v3/console/plugin/config with localOnly=true where applying the new config throws an uncaught runtime error: an NPE/class-cast inside the plugin, or an IO failure writing the local plugin state/config file.

Common situations: Plugin implementation bug; corrupted local plugin state file; read-only or missing plugin config directory; invalid config value that passed schema validation but broke the plugin's apply path.

Related errors

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