alibaba/nacos · error · IllegalArgumentException

Agent directory metadata is only allowed when creating the f

Error message

Agent directory metadata is only allowed when creating the first draft

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java:260

            throw new IllegalArgumentException("Agent draft request must not be null");
        }
        AgentValidationUtils.validateNamespaceId(namespaceId);
        request.validate();
        String agentName = request.getAgentName();
        AgentVersionDetail draft = toDraft(request);
        AiResource meta = resourceManager.findMeta(namespaceId, agentName, RESOURCE_TYPE);
        AgentVersionDetail result;
        if (meta == null) {
            requireInitialDraftContent(request);
            result = persistenceService.createInitialDraft(toInitialAgent(namespaceId, request),
                draft);
        } else {
            VisibilityHelper.checkWritableResource(meta);
            if (hasInitialAgentMetadata(request)) {
                requireInitialDraftContent(request);
                if (!request.getVersion().equals(
                    AiResourceManager.requireVersionInfo(meta).getEditingVersion())) {
                    throw new IllegalArgumentException(
                        "Agent directory metadata is only allowed when creating the first draft");
                }
                result = persistenceService.createInitialDraft(toInitialAgent(namespaceId, request),
                    draft);
            } else {
                result = persistenceService.createDraft(namespaceId, agentName, draft,
                    request.getBasedOnVersion());
            }
        }
        AiResourceTraceService.logSuccess(RESOURCE_TYPE, agentName, request.getVersion(),
            AiResourceTraceService.OP_CREATE_DRAFT, VisibilityHelper.resolveCurrentIdentity(),
            VisibilityHelper.resolveClientIp());
        return result;
    }
    
    /**
     * Register the first directly-online Version through the legacy A2A management facade.
     *

View on GitHub (pinned to 9b989acdf1)

Solutions

1. For subsequent drafts on an existing agent, omit the initial Agent-level metadata fields from the request.
2. If you must include metadata, ensure request.getVersion() matches the resource's current editing version.
3. Separate 'create agent' from 'create draft version' in the client — only the first should carry directory metadata.
4. Fetch the current editing version before submitting if re-supplying metadata.

Example fix

// before — subsequent draft still carries initial metadata
AgentDraftCreateRequest req = buildFullRequest(); // includes agent metadata
req.setVersion("2.0.0");
service.createDraft(ns, req);

// after — clear initial metadata for non-first drafts
AgentDraftCreateRequest req = buildDraftOnlyRequest(); // no agent-level metadata
req.setVersion("2.0.0");
service.createDraft(ns, req);

// For non-first drafts, clear initial agent metadata
if (agentAlreadyExists(ns, agentName)) {
    request.clearInitialAgentMetadata(); // or omit agent-level fields
    AiResource meta = resourceManager.findMeta(ns, agentName, RESOURCE_TYPE);
    String editingVersion = AiResourceManager.requireVersionInfo(meta).getEditingVersion();
    request.setVersion(editingVersion);
}
agentOperationService.createDraft(ns, request);

public static boolean isSafeForSubsequentDraft(
        AgentDraftCreateRequest request, boolean agentExists,
        String currentEditingVersion) {
    if (!agentExists) {
        return true; // first draft — metadata allowed
    }
    if (!hasInitialAgentMetadata(request)) {
        return true; // no metadata — safe
    }
    // metadata only allowed if version matches editing version
n    return request.getVersion() != null && request.getVersion().equals(currentEditingVersion);
}

try {
    agentOperationService.createDraft(ns, request);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("only allowed when creating the first draft")) {
        // strip metadata and retry as a normal draft
        request.clearInitialAgentMetadata();
        agentOperationService.createDraft(ns, request);
    } else {
        throw e;
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Agent direct-online request must contain callInterfaces
• 20002
• 10000
• 10000
• Agent draft request must not be null

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