alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

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

What it means

Thrown by A2aNoopHandler.registerAgent. This noop handler is the active A2aHandler bean (@ConditionalOnMissingBean) when no real implementation is present, i.e., when the deployment does not include both the naming and config modules needed by the AI A2A feature. 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/A2aNoopHandler.java:54

import java.util.List;

/**
 * A2a inner handler.
 *
 * @author KiteSoar
 */
@Component
@ConditionalOnMissingBean(value = A2aHandler.class, ignored = A2aNoopHandler.class)
public class A2aNoopHandler implements A2aHandler {
    
    private static final String A2A_NOT_ENABLED_MESSAGE =
        "Nacos AI A2A module and API required both `naming` and `config` module.";
    
    @Override
    public void registerAgent(AgentCard agentCard, AgentCardForm agentCardForm)
        throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            A2A_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public AgentCardDetailInfo getAgentCardWithVersions(AgentForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            A2A_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public void deleteAgent(AgentForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            A2A_NOT_ENABLED_MESSAGE);
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Deploy a Nacos build that includes both the naming and config modules so the real A2aHandler bean is loaded.
2. Do not call A2A endpoints in deployments that intentionally omit the feature.
3. Verify the active A2aHandler is the real implementation (not A2aNoopHandler) before invoking register operations.

Example fix

// before: calling A2A register on a feature-disabled server
a2aHandler.registerAgent(agentCard, form); // -> 501 API_FUNCTION_DISABLED

// after: gate on feature availability, or enable the module
if (a2aHandler instanceof A2aNoopHandler) {
    throw new IllegalStateException("A2A requires naming+config modules; enable them first");
}
a2aHandler.registerAgent(agentCard, form);

// Feature-detect: only call A2A register if the real handler is present
if (a2aHandler instanceof A2aNoopHandler) {
    throw new ServiceException("A2A feature not enabled (requires naming+config modules)");
}
a2aHandler.registerAgent(agentCard, form);

// Java: boolean guard for A2A availability
boolean a2aEnabled = !(a2aHandler instanceof A2aNoopHandler);

try {
    a2aHandler.registerAgent(agentCard, form);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.API_FUNCTION_DISABLED.getCode()) {
        // A2A not deployed; skip or queue
    } else { throw e; }
}

When it happens

Trigger: Calling the A2A register-agent API on a Nacos server build that does not bundle the A2A implementation (missing naming or config module), so the noop handler is wired instead of the real one.

Common situations: Running a slim/serverless or custom Nacos distribution without the AI module; enabling AI A2A endpoints before installing both naming and config modules; calling A2A APIs in an environment that intentionally excludes them.

Related errors

• API_FUNCTION_DISABLED
• PARAMETER_VALIDATE_ERROR
• CONFLICT
• NOT_FOUND
• 10000

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