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.

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)

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.