alibaba/nacos · error · NacosApiException

10000

10000

Error message

Agent endpoint protocolVersion is missing for agent %s version %s. Please set endpoint protocolVersion or card protocolVersion.

What it means

Thrown by LegacyA2aOperationService.injectEndpoint when an agent endpoint's protocolVersion is blank even after falling back to the card-level protocolVersion (fallbackProtocolVersion). ErrorCode.PARAMETER_MISSING is used. Every registered endpoint instance must carry a protocolVersion; if neither the endpoint nor the card provides one, the injection cannot complete.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java:491

        }
        String fallbackProtocolVersion = resolveEndpointFallbackProtocolVersion(agentCard);
        List<AgentInterface> allAgentEndpoints =
            serviceInfo.getHosts().stream().map(AgentCardUtil::buildAgentInterface)
                .toList();
        for (AgentInterface each : allAgentEndpoints) {
            if (StringUtils.isEmpty(each.getProtocolBinding())
                && StringUtils.isNotEmpty(each.getTransport())) {
                each.setProtocolBinding(each.getTransport());
            }
            if (StringUtils.isEmpty(each.getTransport())
                && StringUtils.isNotEmpty(each.getProtocolBinding())) {
                each.setTransport(each.getProtocolBinding());
            }
            if (StringUtils.isEmpty(each.getProtocolVersion())) {
                each.setProtocolVersion(fallbackProtocolVersion);
            }
            if (StringUtils.isEmpty(each.getProtocolVersion())) {
                throw new NacosApiException(NacosException.INVALID_PARAM,
                    ErrorCode.PARAMETER_MISSING,
                    String.format(
                        "Agent endpoint protocolVersion is missing for agent %s version %s. "
                            + "Please set endpoint protocolVersion or card protocolVersion.",
                        agentCard.getName(), agentCard.getVersion()));
            }
        }
        agentCard.setSupportedInterfaces(allAgentEndpoints);
        agentCard.setAdditionalInterfaces(allAgentEndpoints);
        List<AgentInterface> matchTransportEndpoints = allAgentEndpoints.stream()
            .filter(
                agentInterface -> StringUtils.equalsIgnoreCase(agentInterface.getProtocolBinding(),
                    agentCard.getPreferredTransport()))
            .toList();
        AgentInterface randomPreferredTransportEndpoint = randomOne(
            matchTransportEndpoints.isEmpty() ? allAgentEndpoints : matchTransportEndpoints);
        agentCard.setUrl(randomPreferredTransportEndpoint.getUrl());
        agentCard.setPreferredTransport(randomPreferredTransportEndpoint.getProtocolBinding());

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Ensure every registered A2A endpoint instance includes a non-blank protocolVersion in its metadata.
  2. Set a card-level protocolVersion on the AgentCard so it serves as the fallback for endpoints missing it.
  3. Update the agent client SDK to the version that always sends protocolVersion during endpoint registration.
  4. Re-register the endpoints with complete metadata, then retry the getAgentCard query.

Example fix

// before — endpoint registered without protocolVersion
AgentEndpoint ep = new AgentEndpoint();
ep.setAddress("10.0.0.1");
ep.setPort(8080);
ep.setTransport("JSON-RPC");
// protocolVersion missing
endpointOpService.register(parentClientId, ns, agentName, List.of(ep));

// after
AgentEndpoint ep = new AgentEndpoint();
ep.setAddress("10.0.0.1");
ep.setPort(8080);
ep.setTransport("JSON-RPC");
ep.setProtocolVersion("0.3");
endpointOpService.register(parentClientId, ns, agentName, List.of(ep));
Defensive patterns

Strategy: validation

Validate before calling

// Ensure protocolVersion is set on endpoints before registration
for (AgentEndpoint ep : endpoints) {
    if (StringUtils.isBlank(ep.getProtocolVersion())) {
        ep.setProtocolVersion(card.getProtocolVersion()); // fallback
    }
    if (StringUtils.isBlank(ep.getProtocolVersion())) {
        ep.setProtocolVersion("0.3"); // sensible default
    }
}
// also set card-level fallback
agentCard.setProtocolVersion("0.3");

Type guard

public static boolean allEndpointsHaveProtocolVersion(
        Collection<AgentEndpoint> endpoints, String cardFallback) {
    if (endpoints == null) return false;
    String fallback = StringUtils.isNotBlank(cardFallback) ? cardFallback : null;
    return endpoints.stream().allMatch(e ->
        e != null && (StringUtils.isNotBlank(e.getProtocolVersion()) || fallback != null));
}

Try / catch

try {
    a2aService.getAgentCard(ns, agentName, version, "");
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.PARAMETER_MISSING.getCode()
            && e.getMessage().contains("protocolVersion")) {
        // endpoints need re-registration with protocolVersion metadata
        reRegisterEndpointsWithProtocolVersion(ns, agentName, version);
        a2aService.getAgentCard(ns, agentName, version, "");
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: An A2A agent registered endpoints via Naming without setting the protocolVersion metadata on the instances. The agent card itself lacks a protocolVersion, and the registered instances also omit it. This surfaces during getAgentCard when the server tries to enrich the card with live endpoint data.

Common situations: Agent client registers endpoints with incomplete metadata (missing protocolVersion field). A2A SDK version mismatch where newer instances expect protocolVersion but the registering client does not send it. Manual instance registration via Naming API without the required metadata fields.

Related errors

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