alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

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

What it means

Thrown by InstanceNoopHandler.listInstances when functionMode=config. Listing service instances needs the naming module, which ConditionFunctionEnabled.ConditionNamingEnabled does not enable in config-only mode, so Spring loads InstanceNoopHandler and every list call returns API_FUNCTION_DISABLED (40001) / HTTP 501.

Source

Thrown at console/src/main/java/com/alibaba/nacos/console/handler/impl/noop/naming/InstanceNoopHandler.java:46

/**
 * Noop Implementation of InstanceHandler that handles instance-related operations.
 * Used when `naming` module is disabled(functionMode is `config`)
 *
 * @author xiweng.yy
 */
@Service
@ConditionalOnMissingBean(value = InstanceHandler.class, ignored = InstanceNoopHandler.class)
public class InstanceNoopHandler implements InstanceHandler {
    
    private static final String MCP_NOT_ENABLED_MESSAGE =
        "Current functionMode is `config`, naming module is disabled.";
    
    @Override
    public Page<? extends Instance> listInstances(String namespaceId,
        String serviceNameWithoutGroup, String groupName,
        String clusterName, int page, int pageSize) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public void updateInstance(InstanceForm instanceForm, Instance instance) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public void removeInstance(InstanceForm instanceForm, Instance instance) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Route instance-list queries to a node whose functionMode enables naming (unset, =naming, =microservice, or =ai).
2. Restart the node in a naming-capable mode if discovery is actually required here.
3. Verify function_mode via GET /v3/admin/core/state before listing instances.
4. Remove the instance-list call from clients pointed at the config-only cluster.

Example fix

# before
-Dnacos.functionMode=config   # InstanceNoopHandler active -> listInstances -> 501

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

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

try {
    handler.listInstances(namespaceId, serviceName, groupName, clusterName, page, pageSize);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.API_FUNCTION_DISABLED.getCode()) {
        // naming module disabled (functionMode=config) -> skip discovery UI
    } else { throw e; }
}

When it happens

Trigger: GET /v3/console/ns/instance/list or /v3/admin/ns/instance/list?serviceName=...&groupName=...&namespaceId=... against a server started with -Dnacos.functionMode=config. Also any SDK listInstances() call hitting a config-only node.

Common situations: A config-only Nacos node is deployed for configuration management, but a service-discovery dashboard or health check still polls instances here; mismatched functionMode after splitting a cluster into config-only and naming-only nodes.

Related errors

• API_FUNCTION_DISABLED
• API_FUNCTION_DISABLED
• serverList is empty,please check configuration
• 400
• Param 'resourcePattern' is illegal, resourcePattern is blank

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