{"record":{"id":"5edc07d0e0f85087","repo":"alibaba/nacos","slug":"10000-5edc07","errorCode":"10000","errorMessage":"Agent endpoint protocolVersion is missing for agent %s version %s. Please set endpoint protocolVersion or card protocolVersion.","messagePattern":"Agent endpoint protocolVersion is missing for agent (.+?) version (.+?)\\. Please set endpoint protocolVersion or card protocolVersion\\.","errorType":"exception","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java","lineNumber":491,"sourceCode":"        }\n        String fallbackProtocolVersion = resolveEndpointFallbackProtocolVersion(agentCard);\n        List<AgentInterface> allAgentEndpoints =\n            serviceInfo.getHosts().stream().map(AgentCardUtil::buildAgentInterface)\n                .toList();\n        for (AgentInterface each : allAgentEndpoints) {\n            if (StringUtils.isEmpty(each.getProtocolBinding())\n                && StringUtils.isNotEmpty(each.getTransport())) {\n                each.setProtocolBinding(each.getTransport());\n            }\n            if (StringUtils.isEmpty(each.getTransport())\n                && StringUtils.isNotEmpty(each.getProtocolBinding())) {\n                each.setTransport(each.getProtocolBinding());\n            }\n            if (StringUtils.isEmpty(each.getProtocolVersion())) {\n                each.setProtocolVersion(fallbackProtocolVersion);\n            }\n            if (StringUtils.isEmpty(each.getProtocolVersion())) {\n                throw new NacosApiException(NacosException.INVALID_PARAM,\n                    ErrorCode.PARAMETER_MISSING,\n                    String.format(\n                        \"Agent endpoint protocolVersion is missing for agent %s version %s. \"\n                            + \"Please set endpoint protocolVersion or card protocolVersion.\",\n                        agentCard.getName(), agentCard.getVersion()));\n            }\n        }\n        agentCard.setSupportedInterfaces(allAgentEndpoints);\n        agentCard.setAdditionalInterfaces(allAgentEndpoints);\n        List<AgentInterface> matchTransportEndpoints = allAgentEndpoints.stream()\n            .filter(\n                agentInterface -> StringUtils.equalsIgnoreCase(agentInterface.getProtocolBinding(),\n                    agentCard.getPreferredTransport()))\n            .toList();\n        AgentInterface randomPreferredTransportEndpoint = randomOne(\n            matchTransportEndpoints.isEmpty() ? allAgentEndpoints : matchTransportEndpoints);\n        agentCard.setUrl(randomPreferredTransportEndpoint.getUrl());\n        agentCard.setPreferredTransport(randomPreferredTransportEndpoint.getProtocolBinding());","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java#L473-L509","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure every registered A2A endpoint instance includes a non-blank protocolVersion in its metadata.","Set a card-level protocolVersion on the AgentCard so it serves as the fallback for endpoints missing it.","Update the agent client SDK to the version that always sends protocolVersion during endpoint registration.","Re-register the endpoints with complete metadata, then retry the getAgentCard query."],"exampleFix":"// before — endpoint registered without protocolVersion\nAgentEndpoint ep = new AgentEndpoint();\nep.setAddress(\"10.0.0.1\");\nep.setPort(8080);\nep.setTransport(\"JSON-RPC\");\n// protocolVersion missing\nendpointOpService.register(parentClientId, ns, agentName, List.of(ep));\n\n// after\nAgentEndpoint ep = new AgentEndpoint();\nep.setAddress(\"10.0.0.1\");\nep.setPort(8080);\nep.setTransport(\"JSON-RPC\");\nep.setProtocolVersion(\"0.3\");\nendpointOpService.register(parentClientId, ns, agentName, List.of(ep));","handlingStrategy":"validation","validationCode":"// Ensure protocolVersion is set on endpoints before registration\nfor (AgentEndpoint ep : endpoints) {\n    if (StringUtils.isBlank(ep.getProtocolVersion())) {\n        ep.setProtocolVersion(card.getProtocolVersion()); // fallback\n    }\n    if (StringUtils.isBlank(ep.getProtocolVersion())) {\n        ep.setProtocolVersion(\"0.3\"); // sensible default\n    }\n}\n// also set card-level fallback\nagentCard.setProtocolVersion(\"0.3\");","typeGuard":"public static boolean allEndpointsHaveProtocolVersion(\n        Collection<AgentEndpoint> endpoints, String cardFallback) {\n    if (endpoints == null) return false;\n    String fallback = StringUtils.isNotBlank(cardFallback) ? cardFallback : null;\n    return endpoints.stream().allMatch(e ->\n        e != null && (StringUtils.isNotBlank(e.getProtocolVersion()) || fallback != null));\n}","tryCatchPattern":"try {\n    a2aService.getAgentCard(ns, agentName, version, \"\");\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.PARAMETER_MISSING.getCode()\n            && e.getMessage().contains(\"protocolVersion\")) {\n        // endpoints need re-registration with protocolVersion metadata\n        reRegisterEndpointsWithProtocolVersion(ns, agentName, version);\n        a2aService.getAgentCard(ns, agentName, version, \"\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Always set protocolVersion on every registered A2A endpoint instance.","Set a card-level protocolVersion as a safety fallback.","Update the agent client SDK to always include protocolVersion."],"tags":["a2a","agent","endpoint","protocol-version","missing-param","metadata"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}