alibaba/nacos · error · NacosApiException

20004

20004

Error message

{type} not found: {name}

What it means

Thrown by the generic requireMeta helper in AiResourceManager when aiResourcePersistService.find returns null for the given namespace, name, and type. This is the shared NOT_FOUND guard used across all AI resource types (prompt, agent, skill, etc.). HTTP 404 RESOURCE_NOT_FOUND (code 20004). The message interpolates the resource type and name.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/resource/AiResourceManager.java:365

            AiResource latest = aiResourcePersistService.find(namespaceId, meta.getName(),
                meta.getType());
            if (latest == null || latest.getMetaVersion() == null) {
                return;
            }
            expected = latest.getMetaVersion();
        }
    }
    
    // ---- 2.2 Query / validation helpers ----
    
    /**
     * Load meta row or throw NOT_FOUND.
     */
    public AiResource requireMeta(String namespaceId, String name, String type)
        throws NacosException {
        AiResource meta = aiResourcePersistService.find(namespaceId, name, type);
        if (meta == null) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
                type + " not found: " + name);
        }
        return meta;
    }
    
    /**
     * Find meta row by namespace/name/type.
     */
    public AiResource findMeta(String namespaceId, String name, String type) {
        return aiResourcePersistService.find(namespaceId, name, type);
    }
    
    /**
     * Find version row by namespace/name/type/version.
     */
    public AiResourceVersion findVersion(String namespaceId, String name, String type,
        String version) {
        return aiResourceVersionPersistService.find(namespaceId, name, type, version);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify the resource name, type, and namespace against a list API before calling require-dependent operations.
2. Confirm the resource was created in the correct namespace.
3. If deleted, re-create the resource.
4. Double-check the type parameter matches the resource kind (prompt vs agent vs skill).

Example fix

// before
AiResource meta = resourceManager.requireMeta(ns, "my-agent", "prompt"); // wrong type

// after
AiResource meta = resourceManager.requireMeta(ns, "my-agent", "agent");

// Check resource existence before require-dependent operations
AiResource meta = resourceManager.findMeta(ns, name, type);
if (meta == null) {
    // resource does not exist — create or report
    return;
}

boolean resourceExists = resourceManager.findMeta(ns, name, type) != null;

try {
    AiResource meta = resourceManager.requireMeta(ns, name, type);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.NOT_FOUND) {
        // resource not found — create it or return friendly error
    }
    throw e;
}

When it happens

Trigger: Any AI resource operation that calls requireMeta with a name/type combination that has no metadata row. Common in agent, skill, MCP server, and A2A flows — not just prompts.

Common situations: Referencing a resource that was never created; namespace mismatch; resource was deleted; typo in the resource name; querying the wrong resource type (e.g. looking for a skill name in the agent type).

Related errors

• RESOURCE_NOT_FOUND
• MCP server not found in registry: + externalId
• RESOURCE_NOT_FOUND
• RESOURCE_NOT_FOUND
• MCP_SERVER_NOT_FOUND

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