{"record":{"id":"bde3a54db487e159","repo":"alibaba/nacos","slug":"agent-directory-metadata-is-only-allowed-when-crea","errorCode":null,"errorMessage":"Agent directory metadata is only allowed when creating the first draft","messagePattern":"Agent directory metadata is only allowed when creating the first draft","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java","lineNumber":260,"sourceCode":"            throw new IllegalArgumentException(\"Agent draft request must not be null\");\n        }\n        AgentValidationUtils.validateNamespaceId(namespaceId);\n        request.validate();\n        String agentName = request.getAgentName();\n        AgentVersionDetail draft = toDraft(request);\n        AiResource meta = resourceManager.findMeta(namespaceId, agentName, RESOURCE_TYPE);\n        AgentVersionDetail result;\n        if (meta == null) {\n            requireInitialDraftContent(request);\n            result = persistenceService.createInitialDraft(toInitialAgent(namespaceId, request),\n                draft);\n        } else {\n            VisibilityHelper.checkWritableResource(meta);\n            if (hasInitialAgentMetadata(request)) {\n                requireInitialDraftContent(request);\n                if (!request.getVersion().equals(\n                    AiResourceManager.requireVersionInfo(meta).getEditingVersion())) {\n                    throw new IllegalArgumentException(\n                        \"Agent directory metadata is only allowed when creating the first draft\");\n                }\n                result = persistenceService.createInitialDraft(toInitialAgent(namespaceId, request),\n                    draft);\n            } else {\n                result = persistenceService.createDraft(namespaceId, agentName, draft,\n                    request.getBasedOnVersion());\n            }\n        }\n        AiResourceTraceService.logSuccess(RESOURCE_TYPE, agentName, request.getVersion(),\n            AiResourceTraceService.OP_CREATE_DRAFT, VisibilityHelper.resolveCurrentIdentity(),\n            VisibilityHelper.resolveClientIp());\n        return result;\n    }\n    \n    /**\n     * Register the first directly-online Version through the legacy A2A management facade.\n     *","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java#L242-L278","documentation":"Thrown by AgentOperationService.createDraft as an IllegalArgumentException when the request contains initial Agent-level directory metadata (hasInitialAgentMetadata) but the target version does not match the resource's current editing version. Initial metadata (agent-level catalog/presentation) is only accepted when creating the very first draft; subsequent drafts must not re-supply it unless they target the editing version.","triggerScenarios":"Calling createDraft for an already-existing agent with initial metadata fields populated AND a version that differs from the agent's current editing version. Re-sending the first-draft request (with agent metadata) for a different version after the agent already exists.","commonSituations":"Client reuses the initial-create request template for subsequent drafts without clearing agent-level metadata. Frontend sends the full agent form (including directory metadata) on every draft create. Version mismatch where the client's editing version is stale.","solutions":["For subsequent drafts on an existing agent, omit the initial Agent-level metadata fields from the request.","If you must include metadata, ensure request.getVersion() matches the resource's current editing version.","Separate 'create agent' from 'create draft version' in the client — only the first should carry directory metadata.","Fetch the current editing version before submitting if re-supplying metadata."],"exampleFix":"// before — subsequent draft still carries initial metadata\nAgentDraftCreateRequest req = buildFullRequest(); // includes agent metadata\nreq.setVersion(\"2.0.0\");\nservice.createDraft(ns, req);\n\n// after — clear initial metadata for non-first drafts\nAgentDraftCreateRequest req = buildDraftOnlyRequest(); // no agent-level metadata\nreq.setVersion(\"2.0.0\");\nservice.createDraft(ns, req);","handlingStrategy":"validation","validationCode":"// For non-first drafts, clear initial agent metadata\nif (agentAlreadyExists(ns, agentName)) {\n    request.clearInitialAgentMetadata(); // or omit agent-level fields\n    AiResource meta = resourceManager.findMeta(ns, agentName, RESOURCE_TYPE);\n    String editingVersion = AiResourceManager.requireVersionInfo(meta).getEditingVersion();\n    request.setVersion(editingVersion);\n}\nagentOperationService.createDraft(ns, request);","typeGuard":"public static boolean isSafeForSubsequentDraft(\n        AgentDraftCreateRequest request, boolean agentExists,\n        String currentEditingVersion) {\n    if (!agentExists) {\n        return true; // first draft — metadata allowed\n    }\n    if (!hasInitialAgentMetadata(request)) {\n        return true; // no metadata — safe\n    }\n    // metadata only allowed if version matches editing version\nn    return request.getVersion() != null && request.getVersion().equals(currentEditingVersion);\n}","tryCatchPattern":"try {\n    agentOperationService.createDraft(ns, request);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"only allowed when creating the first draft\")) {\n        // strip metadata and retry as a normal draft\n        request.clearInitialAgentMetadata();\n        agentOperationService.createDraft(ns, request);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Separate 'create agent' from 'create draft version' in client code.","Only include agent-level directory metadata on the first draft.","For subsequent drafts, omit metadata fields entirely."],"tags":["agent","draft","illegal-argument","metadata","version","validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}