alibaba/nacos · error · NacosException

501

501

Error message

Agent discovery is not implemented by this AiService.

What it means

Thrown by the default AgentDiscoveryService.searchAgents() implementation (HTTP 501 SERVER_NOT_IMPLEMENTED). This default exists for binary compatibility with third-party AiService implementations compiled before the Agent discovery surface (added in 3.3.0). The official Nacos client overrides it; a custom or stub AiService that does not override it will hit this default and reject the call.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/AgentDiscoveryService.java:52

 * <p>Default implementations preserve binary compatibility for third-party
 * {@link AiService} implementations compiled before this interface was introduced. Official
 * Nacos clients override the complete surface.</p>
 *
 * @author Nacos
 */
public interface AgentDiscoveryService {
    
    /**
     * Search visible Agent catalog entries.
     *
     * @param request search request
     * @return Agent catalog page
     * @throws NacosException when validation or the remote request fails
     */
    @Since("3.3.0")
    default Page<AgentCatalogEntry> searchAgents(AgentSearchRequest request)
        throws NacosException {
        throw new NacosException(NacosException.SERVER_NOT_IMPLEMENTED,
            "Agent discovery is not implemented by this AiService.");
    }
    
    /**
     * Discover the latest, exact-version, or labeled Agent referenced by {@code reference}.
     *
     * @param reference Agent reference
     * @return complete discovery snapshot
     * @throws NacosException when validation or the remote request fails
     */
    @Since("3.3.0")
    default AgentDiscoveryResult discoverAgent(AgentReference reference) throws NacosException {
        return discoverAgent(reference, null);
    }
    
    /**
     * Discover one Agent and filter its call interfaces and Endpoint sets.
     *

View on GitHub (pinned to 9b989acdf1)

Solutions

Use the official Nacos client (NacosAiService) which overrides all Agent discovery methods.
Upgrade your client SDK to >= 3.3.0 where the Agent discovery surface is fully implemented.
If you maintain a custom AiService, override searchAgents to delegate to the real discovery backend.
Guard capability by checking the SDK version or feature flag before calling Agent methods.

Example fix

// before (custom/stub AiService)
AiService service = MyCustomAiServiceFactory.create();
service.searchAgents(req); // -> 501

// after (official client)
NacosAiService service = NacosAiServiceFactory.create(props);
service.searchAgents(req); // implemented

Defensive patterns

Strategy: try-catch

Validate before calling

public boolean supportsAgentDiscovery(AiService service) {
    try {
        // probe a no-op-capable method or check version metadata
        return service.getClass().getMethod("searchAgents", AgentSearchRequest.class)
            .getDeclaringClass() != AgentDiscoveryService.class;
    } catch (NoSuchMethodException e) {
        return false;
    }
}

Type guard

boolean isOfficialAiService(AiService service) {
    return service instanceof NacosAiService;
}

Try / catch

try {
    Page<AgentCatalogEntry> page = aiService.searchAgents(req);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED) {
        // fall back: use legacy discovery or upgrade the client
        log.warn("Agent discovery unsupported by this AiService; upgrade to >= 3.3.0");
    } else {
        throw e;
    }
}

Prevention

Use the official NacosAiService client (>= 3.3.0) for the full Agent discovery surface.
Before calling Agent methods on an injected AiService, check it is not the default stub.
In custom SPI implementations, override all Agent discovery methods rather than relying on defaults.

When it happens

Trigger: Calling aiService.searchAgents(request) on an AiService instance whose concrete class does not override searchAgents — e.g., a third-party/stub AiService implementation, a mock in tests, or an older client version predating 3.3.0 that only implements the legacy MCP/prompt methods.

Common situations: Using a custom AiService SPI implementation that was written against an older API and never added the Agent discovery methods; a test mock that implements the interface but leaves defaults; a client SDK version older than 3.3.0; downgrading from a newer client to an older one.

Related errors

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