alibaba/nacos · error · NacosApiException

RESOURCE_NOT_FOUND

RESOURCE_NOT_FOUND

Error message

AgentSpec not found: {agentSpecName}

What it means

Thrown by AgentSpecOperationServiceImpl.getAgentSpecDetail when resourceManager.findMeta() returns null for the given namespaceId + agentSpecName. It means no AgentSpec resource row exists in ai_resource for that name in that namespace, so there is no detail to return. Reported as RESOURCE_NOT_FOUND (HTTP 404).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java:168

    
    @Override
    public AgentSpecMeta getAgentSpecDetail(String namespaceId, String agentSpecName,
        String version)
        throws NacosException {
        return getAgentSpecDetail(namespaceId, agentSpecName);
    }
    
    /**
     * Get AgentSpec detail metadata including all version summaries, labels, and online count.
     */
    @Override
    public AgentSpecMeta getAgentSpecDetail(String namespaceId, String agentSpecName)
        throws NacosException {
        // Step 1: Find meta and verify read permission
        AiResource meta =
            resourceManager.findMeta(namespaceId, agentSpecName, RESOURCE_TYPE_AGENTSPEC);
        if (meta == null) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
                "AgentSpec not found: " + agentSpecName);
        }
        resourceManager.ensureReadableOrNotFound(meta, "AgentSpec not found: " + agentSpecName);
        ResourceVersionInfo versionInfo = AiResourceManager.requireVersionInfo(meta);
        // Step 2: Load all version rows and assemble version summary list
        Page<AiResourceVersion> versionPage =
            resourceManager.listVersions(namespaceId, agentSpecName,
                RESOURCE_TYPE_AGENTSPEC, null, 1, 200);
        List<AgentSpecMeta.AgentSpecVersionSummary> versionSummaries = new ArrayList<>();
        if (versionPage != null && versionPage.getPageItems() != null) {
            for (AiResourceVersion v : versionPage.getPageItems()) {
                if (v == null) {
                    continue;
                }
                AgentSpecMeta.AgentSpecVersionSummary summary =
                    new AgentSpecMeta.AgentSpecVersionSummary();
                summary.setVersion(v.getVersion());
                summary.setStatus(v.getStatus());

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Confirm the agentSpecName is spelled exactly as returned by the list endpoint.
  2. Verify the namespaceId in the request matches the namespace where the AgentSpec was created.
  3. Call the AgentSpec list/search endpoint to see the available names in that namespace.
  4. If the spec was deleted, re-create or re-upload it from its ZIP archive.
Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(agentSpecName)) {
    throw new IllegalArgumentException("agentSpecName is required");
}

Try / catch

try {
    return service.getAgentSpecDetail(namespaceId, agentSpecName);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.NOT_FOUND) {
        return Optional.empty(); // or 404 to the caller
    }
    throw e;
}

Prevention

When it happens

Trigger: GET request for AgentSpec detail where agentSpecName is misspelled, belongs to a different namespace, was never created, or was already deleted.

Common situations: Namespace mismatch (querying the public/default namespace when the spec lives in another); typo in the spec name; the spec was deleted between a list call and the detail call.

Related errors

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