{"record":{"id":"2194730241811859","repo":"alibaba/nacos","slug":"api-function-disabled-219473","errorCode":"API_FUNCTION_DISABLED","errorMessage":"Nacos AI Pipeline module requires both `naming` and `config` module.","messagePattern":"Nacos AI Pipeline module requires both `naming` and `config` module\\.","errorType":"exception","errorClass":"NacosApiException","httpStatus":501,"severity":"error","filePath":"console/src/main/java/com/alibaba/nacos/console/handler/impl/noop/ai/PipelineNoopHandler.java","lineNumber":44,"sourceCode":"import org.springframework.stereotype.Service;\n\n/**\n * Noop implementation of Pipeline handler.\n * Used when AI module is not enabled.\n *\n * @author kiro\n * @since 3.2.0\n */\n@Service\n@ConditionalOnMissingBean(value = PipelineHandler.class, ignored = PipelineNoopHandler.class)\npublic class PipelineNoopHandler implements PipelineHandler {\n    \n    private static final String NOT_ENABLED_MSG =\n        \"Nacos AI Pipeline module requires both `naming` and `config` module.\";\n    \n    @Override\n    public PipelineExecution getPipeline(String pipelineId) throws NacosException {\n        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,\n            ErrorCode.API_FUNCTION_DISABLED, NOT_ENABLED_MSG);\n    }\n    \n    @Override\n    public Page<PipelineExecution> listPipelines(String resourceType, String resourceName,\n        String namespaceId, String version, int pageNo, int pageSize) throws NacosException {\n        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,\n            ErrorCode.API_FUNCTION_DISABLED, NOT_ENABLED_MSG);\n    }\n}\n","sourceCodeStart":26,"sourceCodeEnd":55,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/console/src/main/java/com/alibaba/nacos/console/handler/impl/noop/ai/PipelineNoopHandler.java#L26-L55","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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).","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.","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).","Restart the Nacos server after changing configuration so Spring re-evaluates the @ConditionalOnMissingBean and loads the real handler instead of the noop stub."],"exampleFix":"# before (server start command that disables AI):\njava -Dnacos.functionMode=config -jar nacos-server.jar\n# AI Pipeline and Skill APIs return 501 API_FUNCTION_DISABLED\n\n# after (enable AI by using empty functionMode or 'ai'):\njava -Dnacos.functionMode=ai -jar nacos-server.jar\n# Real PipelineInnerHandler / SkillInnerHandler beans load;\n# @ConditionalOnMissingBean no longer activates the noop stubs.","handlingStrategy":"try-catch","validationCode":"// Before calling any AI Pipeline or Skill API, verify the server has the module enabled:\nimport com.alibaba.nacos.sys.env.EnvUtil;\n\nString functionMode = EnvUtil.getFunctionMode();\nboolean aiEnabled = EnvUtil.getProperty(\"nacos.extension.ai.enabled\", Boolean.class, true);\nboolean aiModuleActive = aiEnabled && (functionMode == null || functionMode.isEmpty() || \"ai\".equalsIgnoreCase(functionMode));\nif (!aiModuleActive) {\n    throw new IllegalStateException(\n        \"AI module is not enabled. Set -Dnacos.functionMode=ai (or leave unset) and nacos.extension.ai.enabled=true.\");\n}\n// Safe to call PipelineHandler / SkillHandler methods below","typeGuard":"// Type guard: check if the injected handler is the noop stub before calling.\nimport com.alibaba.nacos.console.handler.impl.noop.ai.PipelineNoopHandler;\nimport com.alibaba.nacos.console.handler.impl.noop.ai.SkillNoopHandler;\n\nboolean isPipelineNoop = (handler instanceof PipelineNoopHandler);\nboolean isSkillNoop = (handler instanceof SkillNoopHandler);\n// If either is true, every method will throw API_FUNCTION_DISABLED — skip the call or surface a user-friendly message.","tryCatchPattern":"try {\n    handler.someMethod(form);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED\n            && e.getDetailErrCode() == ErrorCode.API_FUNCTION_DISABLED.getCode()) {\n        // AI module is disabled on this server; degrade gracefully\n        log.warn(\"AI feature unavailable: {}\", e.getMessage());\n        return fallbackResponse();\n    }\n    throw e; // re-throw unrelated errors\n}","preventionTips":["After any configuration change, grep the startup log for 'AI module disabled' to confirm the module loaded before calling AI APIs.","Add a health/readiness check that calls a lightweight AI endpoint (e.g. GET /v3/console/ai/skill/list) and fails fast in CI if it returns 501.","Document the nacos.functionMode and nacos.extension.ai.enabled settings in your deployment runbook so operators know the AI module's dependencies.","In integration tests, assert that NacosApiException with SERVER_NOT_IMPLEMENTED is NOT thrown when AI is expected to be enabled.","When assembling a custom Nacos distribution, verify the ai, naming, and config module JARs are all present in the final artifact."],"tags":["nacos","ai-module","feature-disabled","pipeline","ai-registry"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}