alibaba/nacos · error · IllegalArgumentException

Online Agent Version must contain callInterfaces

Error message

Online Agent Version must contain callInterfaces

What it means

An Agent Version that will be persisted directly as 'online' must include a non-null callInterfaces list. This guard in validateOnlineVersionInputs runs before createOnlineVersion writes the Version row, guaranteeing that a published online Version carries at least one protocol endpoint contract so it can be discovered and invoked.

Solutions

Set version.setCallInterfaces(...) with at least one AgentCallInterface before calling createOnlineVersion.
If using the HTTP direct-online API, ensure the request JSON body includes a non-null callInterfaces array.
Verify the upstream AgentDraftCreateRequest carries callInterfaces — validateDirectOnlineRequest rejects null callInterfaces first.

Example fix

// before
AgentVersionDetail v = new AgentVersionDetail();
v.setVersion("1.0.0");
persistenceService.createOnlineVersion(ns, name, v, null); // throws

// after
v.setCallInterfaces(List.of(callInterface));
persistenceService.createOnlineVersion(ns, name, v, null);

Defensive patterns

Strategy: validation

Validate before calling

if (version == null || version.getCallInterfaces() == null || version.getCallInterfaces().isEmpty()) {
    throw new IllegalArgumentException("Online Agent Version requires callInterfaces");
}

Type guard

boolean hasCallInterfaces(AgentVersionDetail v) {
    return v != null && v.getCallInterfaces() != null && !v.getCallInterfaces().isEmpty();
}

Try / catch

try {
    persistenceService.createOnlineVersion(ns, name, version, preferredLatest);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("callInterfaces")) {
        throw new NacosApiException(NacosException.INVALID_PARAM, "callInterfaces is required for online Versions");
    }
    throw e;
}

Prevention

Always populate callInterfaces when building an AgentVersionDetail for the online path.
Use a builder or factory method that enforces callInterfaces as a required field.
Run AgentValidationUtils checks and request.validate() before reaching the persistence layer.

When it happens

Trigger: Calling createOnlineVersion (the internal direct-online Agent Version creation path, reachable from the HTTP direct-online flow POST /v3/admin/ai/agent/draft or the client publish API) with an AgentVersionDetail whose getCallInterfaces() returns null.

Common situations: A client SDK or migration tool builds an AgentVersionDetail for direct-online creation and forgets to populate callInterfaces. A test fixture constructs a Version with only version/author metadata. The toOnlineVersion(request) converter received a request whose callInterfaces were null (normally caught earlier by validateDirectOnlineRequest at line 775).

Related errors

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

Appendix: source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java:1058

            && !agent.getAgentName().equals(initialVersion.getAgentName())) {
            throw new IllegalArgumentException("initialVersion agentName does not match Agent");
        }
        if (initialVersion.getStatus() != null
            && !expectedStatus.equals(initialVersion.getStatus())) {
            throw new IllegalArgumentException("initialVersion status must be " + expectedStatus);
        }
    }
    
    private void validateOnlineVersionInputs(String namespaceId, String agentName,
        AgentVersionDetail version, String preferredLatest) {
        AgentValidationUtils.validateNamespaceId(namespaceId);
        AgentValidationUtils.validateAgentName(agentName);
        if (version == null) {
            throw new IllegalArgumentException("Agent Version must not be null");
        }
        AgentValidationUtils.validateVersion(version.getVersion());
        if (version.getCallInterfaces() == null) {
            throw new IllegalArgumentException("Online Agent Version must contain callInterfaces");
        }
        if (version.getNamespaceId() != null
            && !namespaceId.equals(version.getNamespaceId())) {
            throw new IllegalArgumentException("Agent Version namespaceId does not match request");
        }
        if (version.getAgentName() != null && !agentName.equals(version.getAgentName())) {
            throw new IllegalArgumentException("Agent Version agentName does not match request");
        }
        if (version.getStatus() != null
            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(version.getStatus())) {
            throw new IllegalArgumentException("Agent Version status must be online");
        }
        if (version.getContentDigest() != null || version.getCreateTime() != null
            || version.getUpdateTime() != null) {
            throw new IllegalArgumentException(
                "Agent Version must not contain read-only projection fields");
        }
        if (preferredLatest != null && !version.getVersion().equals(preferredLatest)) {

View on GitHub (pinned to 9b989acdf1)