alibaba/nacos · error · NacosException

501

501

Error message

Agent publication is not implemented by this AiService.

What it means

The publishAgent default method on AiService (Nacos 3.3.0) throws NacosException with code SERVER_NOT_IMPLEMENTED (501) when the concrete AiService implementation does not override it. This means the SDK/server combination does not support publishing Agent Versions from application code through this interface.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/AiService.java:55

 *
 * @author xiweng.yy
 */
public interface AiService extends AgentDiscoveryService, A2aService {
    
    /**
     * Publish one exact Agent Version from application code.
     *
     * <p>The AiService namespace is used automatically. By default this creates a draft;
     * {@link AgentPublishRequest#isAutoSubmit()} requests the ordinary submit pipeline and never
     * force-publishes a Version.</p>
     *
     * @param request Agent definition publication request
     * @return resulting exact Version detail
     * @throws NacosException when validation, publication, or submit fails
     */
    @Since("3.3.0")
    default AgentVersionDetail publishAgent(AgentPublishRequest request) throws NacosException {
        throw new NacosException(NacosException.SERVER_NOT_IMPLEMENTED,
            "Agent publication is not implemented by this AiService.");
    }
    
    /**
     * Get mcp server detail info for the latest published version.
     *
     * @param mcpName name of mcp server
     * @return detail information of MCP server
     * @throws NacosException if request parameter is invalid or mcp server not found or handle error
     */
    @Since("3.0.3")
    default McpServerDetailInfo getMcpServer(String mcpName) throws NacosException {
        return getMcpServer(mcpName, null);
    }
    
    /**
     * Get mcp server detail info.
     *

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure the Nacos server is 3.3.0+ with the AI agent publication module enabled.
2. Override publishAgent in a custom AiService subclass to route to the correct server API.
3. Use the admin/ console HTTP API for agent publication if the SDK path is not yet wired on the server.
4. Verify the AiService factory (e.g. NacosFactory.createAiService) returns a full implementation, not a partial one.

Example fix

// before
AgentVersionDetail detail = aiService.publishAgent(request);

// after -- check capability or use admin API
if (!agentPublicationSupported(aiService)) {
    // POST /v3/admin/ai/agent/publish with the same request body
} else {
    aiService.publishAgent(request);
}

boolean supported;
try {
    java.lang.reflect.Method m = aiService.getClass().getMethod("publishAgent",
        com.alibaba.nacos.api.ai.model.agent.AgentPublishRequest.class);
    supported = !m.getDeclaringClass().equals(com.alibaba.nacos.api.ai.AiService.class);
} catch (NoSuchMethodException e) {
    supported = false;
}

public static boolean supportsAgentPublication(AiService svc) {
    try {
        Method m = svc.getClass().getMethod("publishAgent", AgentPublishRequest.class);
        return !m.getDeclaringClass().equals(AiService.class);
    } catch (NoSuchMethodException e) {
        return false;
    }
}

try {
    aiService.publishAgent(request);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED) {
        // fall back to admin HTTP API for agent publication
    } else throw e;
}

When it happens

Trigger: Invoking aiService.publishAgent(request) where the AiService instance inherits the default stub. Common when the Nacos client SDK version supports the method signature but the connected server does not implement the publication pipeline.

Common situations: Client SDK upgraded to 3.3.0 but server is older. Using a mock AiService in unit tests without stubbing publishAgent. The server-side AI agent publication module is disabled or not deployed.

Related errors

• 501
• SERVER_NOT_IMPLEMENTED
• 501
• 501
• 500

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