alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

Current functionMode is `naming`, config module is disabled.

What it means

Thrown by ConfigNoopHandler.getConfigList, the fallback ConfigHandler bean activated by @ConditionalOnMissingBean when the server runs with -Dnacos.functionMode=naming. Because ConditionFunctionEnabled.ConditionConfigEnabled does not match the 'naming' mode, the real config handler is never registered, so Spring injects ConfigNoopHandler and list-config calls return API_FUNCTION_DISABLED (40001) / HTTP 501.

Source

Thrown at console/src/main/java/com/alibaba/nacos/console/handler/impl/noop/config/ConfigNoopHandler.java:58

/**
 * Noop Implementation of ConfigHandler for handling internal configuration operations.
 * Used when `config` module is disabled(functionMode is `naming`)
 *
 * @author xiweng.yy
 */
@Service
@ConditionalOnMissingBean(value = ConfigHandler.class, ignored = ConfigNoopHandler.class)
public class ConfigNoopHandler implements ConfigHandler {
    
    private static final String MCP_NOT_ENABLED_MESSAGE =
        "Current functionMode is `naming`, config module is disabled.";
    
    @Override
    public Page<ConfigBasicInfo> getConfigList(int pageNo, int pageSize, String dataId,
        String group,
        String namespaceId, Map<String, Object> configAdvanceInfo) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public ConfigDetailInfo getConfigDetail(String dataId, String group, String namespaceId)
        throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public Boolean publishConfig(ConfigForm configForm, ConfigRequestInfo configRequestInfo)
        throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);

View on GitHub (pinned to 9b989acdf1)

Solutions

Do not call config APIs against a naming-only node — target a node whose functionMode enables config (unset, =config, =microservice, or =ai).
Restart the node without -Dnacos.functionMode=naming if config support is actually required for this deployment.
Verify the live mode with GET /v3/admin/core/state (function_mode key) before issuing config-list requests.
Remove the config-list call from clients pointed at the naming-only cluster.

Example fix

# before
-Dnacos.functionMode=naming   # ConfigNoopHandler active -> getConfigList -> 501

# after — enable config on this node
-Dnacos.functionMode=config   # or unset for all-modules

Defensive patterns

Strategy: validation

Validate before calling

// GET {nacos}/v3/admin/core/state -> data["function_mode"]
String mode = serverState.get("function_mode");
boolean configEnabled = (mode == null || mode.isEmpty())
    || "config".equalsIgnoreCase(mode)
    || "microservice".equalsIgnoreCase(mode)
    || "ai".equalsIgnoreCase(mode);
if (!configEnabled) { /* do not call getConfigList; report config disabled */ }

Try / catch

try {
    handler.getConfigList(pageNo, pageSize, dataId, group, namespaceId, advanceInfo);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.API_FUNCTION_DISABLED.getCode()) {
        // config module disabled by functionMode=naming -> skip config UI
    } else { throw e; }
}

Prevention

Keep a known function_mode per cluster node in client config and never send config requests to naming-only nodes.
Cache the result of /v3/admin/core/state at startup and refresh on connection reset.
Gate config-list calls behind a configEnabled check so the UI never issues a 501-guaranteed request.

When it happens

Trigger: GET /v3/console/cs/config/list or /v3/admin/cs/config/list (or any client SDK config-list call routed through the console handler) against a server started with -Dnacos.functionMode=naming.

Common situations: A naming-only Nacos cluster is deployed for pure service discovery, but a tooling/UI still polls the config list. Mismatched functionMode between the node an operator set and the workload expectations after a 2.x->3.x migration.

Related errors

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