{"record":{"id":"bad937c9d8fa30b2","repo":"alibaba/nacos","slug":"resource-not-found-bad937","errorCode":"RESOURCE_NOT_FOUND","errorMessage":"AgentSpec not found: {agentSpecName}","messagePattern":"AgentSpec not found: (.+?)","errorType":"http","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java","lineNumber":168,"sourceCode":"    \n    @Override\n    public AgentSpecMeta getAgentSpecDetail(String namespaceId, String agentSpecName,\n        String version)\n        throws NacosException {\n        return getAgentSpecDetail(namespaceId, agentSpecName);\n    }\n    \n    /**\n     * Get AgentSpec detail metadata including all version summaries, labels, and online count.\n     */\n    @Override\n    public AgentSpecMeta getAgentSpecDetail(String namespaceId, String agentSpecName)\n        throws NacosException {\n        // Step 1: Find meta and verify read permission\n        AiResource meta =\n            resourceManager.findMeta(namespaceId, agentSpecName, RESOURCE_TYPE_AGENTSPEC);\n        if (meta == null) {\n            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,\n                \"AgentSpec not found: \" + agentSpecName);\n        }\n        resourceManager.ensureReadableOrNotFound(meta, \"AgentSpec not found: \" + agentSpecName);\n        ResourceVersionInfo versionInfo = AiResourceManager.requireVersionInfo(meta);\n        // Step 2: Load all version rows and assemble version summary list\n        Page<AiResourceVersion> versionPage =\n            resourceManager.listVersions(namespaceId, agentSpecName,\n                RESOURCE_TYPE_AGENTSPEC, null, 1, 200);\n        List<AgentSpecMeta.AgentSpecVersionSummary> versionSummaries = new ArrayList<>();\n        if (versionPage != null && versionPage.getPageItems() != null) {\n            for (AiResourceVersion v : versionPage.getPageItems()) {\n                if (v == null) {\n                    continue;\n                }\n                AgentSpecMeta.AgentSpecVersionSummary summary =\n                    new AgentSpecMeta.AgentSpecVersionSummary();\n                summary.setVersion(v.getVersion());\n                summary.setStatus(v.getStatus());","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java#L150-L186","documentation":"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).","triggerScenarios":"GET request for AgentSpec detail where agentSpecName is misspelled, belongs to a different namespace, was never created, or was already deleted.","commonSituations":"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.","solutions":["Confirm the agentSpecName is spelled exactly as returned by the list endpoint.","Verify the namespaceId in the request matches the namespace where the AgentSpec was created.","Call the AgentSpec list/search endpoint to see the available names in that namespace.","If the spec was deleted, re-create or re-upload it from its ZIP archive."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (StringUtils.isBlank(agentSpecName)) {\n    throw new IllegalArgumentException(\"agentSpecName is required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return service.getAgentSpecDetail(namespaceId, agentSpecName);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == NacosException.NOT_FOUND) {\n        return Optional.empty(); // or 404 to the caller\n    }\n    throw e;\n}","preventionTips":["Validate agentSpecName is non-blank before calling.","Use the list endpoint to confirm names in a namespace before detail lookups.","Treat 404 as a normal control-flow outcome, not an exceptional one, in UI clients."],"tags":["agentspec","not-found","resource","read"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}