alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

Nacos AI Pipeline module requires both `naming` and `config` module.

What it means

This error is thrown by PipelineNoopHandler, a stub implementation activated via @ConditionalOnMissingBean when no real PipelineHandler bean exists on the Spring context. It signals that the Nacos AI Pipeline feature 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/PipelineNoopHandler.java:44

import org.springframework.stereotype.Service;

/**
 * Noop implementation of Pipeline handler.
 * Used when AI module is not enabled.
 *
 * @author kiro
 * @since 3.2.0
 */
@Service
@ConditionalOnMissingBean(value = PipelineHandler.class, ignored = PipelineNoopHandler.class)
public class PipelineNoopHandler implements PipelineHandler {
    
    private static final String NOT_ENABLED_MSG =
        "Nacos AI Pipeline module requires both `naming` and `config` module.";
    
    @Override
    public PipelineExecution getPipeline(String pipelineId) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED, NOT_ENABLED_MSG);
    }
    
    @Override
    public Page<PipelineExecution> listPipelines(String resourceType, String resourceName,
        String namespaceId, String version, int pageNo, int pageSize) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED, NOT_ENABLED_MSG);
    }
}

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.
Defensive patterns

Strategy: try-catch

Validate before calling

// 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

// 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 / catch

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
}

Prevention

When it happens

Trigger: Calling GET /v3/console/ai/pipeline?pipelineId=<id> (or the handler's getPipeline method) when the server has no real PipelineHandler bean — e.g. functionMode is set to 'config', 'naming', or 'microservice', or nacos.extension.ai.enabled=false.

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

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