alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

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

What it means

This error is thrown by SkillNoopHandler, a stub implementation activated via @ConditionalOnMissingBean when no real SkillHandler bean exists on the Spring context. It signals that the Nacos AI Skill management API is unavailable because the server is running without both the `naming` and `config` modules enabled. The HTTP response carries status 501 (SERVER_NOT_IMPLEMENTED) with detail error code API_FUNCTION_DISABLED (40001).

Source

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

import java.util.List;

/**
 * Noop implementation of Skill handler.
 * Used when AI module is not enabled or both `naming` and `config` modules are not available.
 *
 * @author nacos
 */
@Service
@ConditionalOnMissingBean(value = SkillHandler.class, ignored = SkillNoopHandler.class)
public class SkillNoopHandler implements SkillHandler {
    
    private static final String SKILL_NOT_ENABLED_MESSAGE =
        "Nacos AI Skill module and API required both `naming` and `config` module.";
    
    @Override
    public SkillMeta getSkill(SkillForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            SKILL_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public Skill getSkillVersion(SkillForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            SKILL_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public Skill downloadSkillVersion(SkillForm form) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            SKILL_NOT_ENABLED_MESSAGE);
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set the JVM system property -Dnacos.functionMode=ai (or leave it unset for all-modules mode) so the ConditionAiEnabled check passes and the real handler beans load.
2. Ensure nacos.extension.ai.enabled is not set to false in application.properties or custom.toml (it defaults to true; explicitly set it to true if overridden elsewhere).
3. Verify both the `naming` and `config` module JARs are on the server classpath (the AI module depends on both). If running a custom assembly, include config, naming, and ai modules.
4. If using deployment type console or server, confirm nacos.deployment.type is set correctly and the target Nacos server actually has the AI module loaded (check startup logs for 'AI module disabled' warnings).
5. Restart the Nacos server after changing configuration so Spring re-evaluates the @ConditionalOnMissingBean and loads the real handler instead of the noop stub.

Example fix

# before (server start command that disables AI):
java -Dnacos.functionMode=config -jar nacos-server.jar
# AI Pipeline and Skill APIs return 501 API_FUNCTION_DISABLED

# after (enable AI by using empty functionMode or 'ai'):
java -Dnacos.functionMode=ai -jar nacos-server.jar
# Real PipelineInnerHandler / SkillInnerHandler beans load;
# @ConditionalOnMissingBean no longer activates the noop stubs.

// Before calling any AI Pipeline or Skill API, verify the server has the module enabled:
import com.alibaba.nacos.sys.env.EnvUtil;

String functionMode = EnvUtil.getFunctionMode();
boolean aiEnabled = EnvUtil.getProperty("nacos.extension.ai.enabled", Boolean.class, true);
boolean aiModuleActive = aiEnabled && (functionMode == null || functionMode.isEmpty() || "ai".equalsIgnoreCase(functionMode));
if (!aiModuleActive) {
    throw new IllegalStateException(
        "AI module is not enabled. Set -Dnacos.functionMode=ai (or leave unset) and nacos.extension.ai.enabled=true.");
}
// Safe to call PipelineHandler / SkillHandler methods below

// Type guard: check if the injected handler is the noop stub before calling.
import com.alibaba.nacos.console.handler.impl.noop.ai.PipelineNoopHandler;
import com.alibaba.nacos.console.handler.impl.noop.ai.SkillNoopHandler;

boolean isPipelineNoop = (handler instanceof PipelineNoopHandler);
boolean isSkillNoop = (handler instanceof SkillNoopHandler);
// If either is true, every method will throw API_FUNCTION_DISABLED — skip the call or surface a user-friendly message.

try {
    handler.someMethod(form);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED
            && e.getDetailErrCode() == ErrorCode.API_FUNCTION_DISABLED.getCode()) {
        // AI module is disabled on this server; degrade gracefully
        log.warn("AI feature unavailable: {}", e.getMessage());
        return fallbackResponse();
    }
    throw e; // re-throw unrelated errors
}

When it happens

Trigger: Calling GET /v3/console/ai/skill (getSkill) with a SkillForm containing namespaceId and skillName when the server has no real SkillHandler bean.

Common situations: Running Nacos with nacos.functionMode=config or nacos.functionMode=naming to isolate a single function, which disables the AI module and its dependent handlers. | Running Nacos with nacos.functionMode=microservice (config+naming without AI), which leaves AI handlers inactive. | Explicitly setting nacos.extension.ai.enabled=false in application.properties or custom.properties to disable AI features. | Using a custom Nacos server assembly that omits the ai module JAR or one of its dependencies (config or naming). | Upgrading Nacos to 3.2.0+ where AI features were introduced but the deployment configuration was not updated to enable them.

Related errors

• API_FUNCTION_DISABLED
• 10000
• DATA_ACCESS_ERROR
• HTTP + result.getStatusCode() + when fetching + result.ge
• HTTP + result.getStatusCode() + when fetching + url

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