alibaba/nacos · error · IllegalArgumentException

Agent draft must contain either callInterfaces or basedOnVer

Error message

Agent draft must contain either callInterfaces or basedOnVersion

What it means

AgentDraftCreateRequest.validate enforces an XOR constraint: exactly one of callInterfaces (direct content) or basedOnVersion (copy from an existing version) must be provided. Setting both or neither triggers this error. This prevents ambiguous draft creation where the content source is unclear.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentDraftCreateRequest.java:68

    
    private List<AgentCallInterface> callInterfaces;
    
    private String author;
    
    private String changeDescription;
    
    private String basedOnVersion;
    
    /**
     * Validate the draft identity and content source.
     */
    public void validate() {
        AgentAdminRequestUtils.validateIdentity(agentName);
        AgentAdminRequestUtils.validateVersion(version);
        boolean directContent = callInterfaces != null;
        boolean copiedContent = !AgentAdminRequestUtils.isBlank(basedOnVersion);
        if (directContent == copiedContent) {
            throw new IllegalArgumentException(
                "Agent draft must contain either callInterfaces or basedOnVersion");
        }
        if (copiedContent) {
            AgentAdminRequestUtils.validateVersion(basedOnVersion);
        }
    }
    
    public String getAgentName() {
        return agentName;
    }
    
    public void setAgentName(String agentName) {
        this.agentName = agentName;
    }
    
    public String getDisplayName() {
        return displayName;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide callInterfaces with at least one interface when creating a draft from scratch, and leave basedOnVersion null.
2. Provide basedOnVersion (an existing version string) when copying, and leave callInterfaces null.
3. Ensure your API client does not default callInterfaces to an empty list when it should be absent.
4. Add a pre-validation check in your controller/service layer to enforce the XOR before calling validate().

Example fix

// before
request.setCallInterfaces(List.of(iface));
request.setBasedOnVersion("1.0.0"); // both set -> error

// after -- direct content path
request.setCallInterfaces(List.of(iface));
request.setBasedOnVersion(null);

// OR copy path
request.setCallInterfaces(null);
request.setBasedOnVersion("1.0.0");

boolean hasInterfaces = request.getCallInterfaces() != null;
boolean hasBasedOn = request.getBasedOnVersion() != null
    && !request.getBasedOnVersion().trim().isEmpty();
if (hasInterfaces == hasBasedOn) {
    throw new IllegalArgumentException(
        "Provide exactly one of callInterfaces or basedOnVersion");
}

public static boolean isDraftCreateValid(AgentDraftCreateRequest req) {
    boolean d = req.getCallInterfaces() != null;
    boolean c = req.getBasedOnVersion() != null && !req.getBasedOnVersion().isBlank();
    return d ^ c;
}

try {
    request.validate();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("either callInterfaces or basedOnVersion")) {
        return badRequest("Specify exactly one content source for the draft");
    }
    throw e;
}

When it happens

Trigger: Calling draftCreate.validate() when both callInterfaces and basedOnVersion are populated, or when both are null/blank. The method checks directContent == copiedContent (true when both are true or both are false).

Common situations: A form or API payload sends both fields. A client defaults callInterfaces to an empty list (non-null) AND sets basedOnVersion, triggering the both-set branch. Forgetting to populate either field in a create request.

Related errors

• callInterfaces must not be null
• PARAMETER_MISSING
• PARAMETER_VALIDATE_ERROR
• Agent directory metadata is only allowed when creating the f
• 20002

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