alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

Nacos AI AgentSpec module and API required both `naming` and `config` module.

What it means

Thrown by AgentSpecNoopHandler.getAgentSpec when retrieving agent-spec metadata. The noop handler is the active AgentSpecHandler bean (@ConditionalOnMissingBean) when the deployment lacks both the naming and config modules required by the AI AgentSpec feature, so it raises NacosApiException with NacosException.SERVER_NOT_IMPLEMENTED (HTTP 501) and ErrorCode.API_FUNCTION_DISABLED.

Source

Thrown at console/src/main/java/com/alibaba/nacos/console/handler/impl/noop/ai/AgentSpecNoopHandler.java:57

import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.stereotype.Service;

/**
 * Noop implementation of AgentSpec handler.
 * Used when AI module is not enabled or both `naming` and `config` modules are not available.
 *
 * @author nacos
 */
@Service
@ConditionalOnMissingBean(value = AgentSpecHandler.class, ignored = AgentSpecNoopHandler.class)
public class AgentSpecNoopHandler implements AgentSpecHandler {
    
    private static final String AGENTSPEC_NOT_ENABLED_MESSAGE =
        "Nacos AI AgentSpec module and API required both `naming` and `config` module.";
    
    @Override
    public AgentSpecMeta getAgentSpec(AgentSpecForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            AGENTSPEC_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public AgentSpec getAgentSpecVersion(AgentSpecForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            AGENTSPEC_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public void deleteAgentSpec(AgentSpecForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            AGENTSPEC_NOT_ENABLED_MESSAGE);
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Deploy Nacos with both naming and config modules to activate the real AgentSpecHandler.
2. Do not call AgentSpec APIs on deployments that intentionally exclude the feature.
3. Detect the noop handler at startup and disable AgentSpec flows in your client.

Example fix

// before
AgentSpecMeta m = agentSpecHandler.getAgentSpec(form); // -> 501

// after
if (agentSpecHandler instanceof AgentSpecNoopHandler) {
    throw new IllegalStateException("AgentSpec requires naming+config modules; enable them first");
}
AgentSpecMeta m = agentSpecHandler.getAgentSpec(form);

// Feature-detect: only call AgentSpec get when the real handler is present
if (agentSpecHandler instanceof AgentSpecNoopHandler) {
    throw new ServiceException("AgentSpec feature not enabled (requires naming+config modules)");
}
return agentSpecHandler.getAgentSpec(form);

// Java: boolean guard for AgentSpec availability
boolean agentSpecEnabled = !(agentSpecHandler instanceof AgentSpecNoopHandler);

try {
    return agentSpecHandler.getAgentSpec(form);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.API_FUNCTION_DISABLED.getCode()) {
        // feature not deployed; skip or surface message
    } else { throw e; }
}

When it happens

Trigger: Calling the AgentSpec get API on a Nacos server build that does not bundle the real AgentSpecHandler (missing naming or config module).

Common situations: Custom/slim Nacos distribution without the AI AgentSpec module; calling AgentSpec endpoints before enabling the feature.

Related errors

• API_FUNCTION_DISABLED
• 10000
• 20002
• 10000
• 10000

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