{"record":{"id":"2d8751fc23183cfe","repo":"alibaba/nacos","slug":"20002-2d8751","errorCode":"20002","errorMessage":"Required parameter 'registrationType' value should be `%s` or `%s` but was `%s`","messagePattern":"Required parameter 'registrationType' value should be `(.+?)` or `(.+?)` but was `(.+?)`","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/form/a2a/admin/AgentCardForm.java","lineNumber":57,"sourceCode":"    private String agentCard;\n    \n    @Override\n    public void validate() throws NacosApiException {\n        fillDefaultNamespaceId();\n        fillDefaultRegistrationType();\n        if (StringUtils.isEmpty(agentCard)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Request parameter `agentCard` should not be `null` or empty.\");\n        }\n        validateRegistrationType();\n        \n    }\n    \n    protected void validateRegistrationType() throws NacosApiException {\n        if (!A2A_ENDPOINT_TYPE_URL.equals(getRegistrationType())\n            && !A2A_ENDPOINT_TYPE_SERVICE.equals(\n                getRegistrationType())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                String.format(\n                    \"Required parameter 'registrationType' value should be `%s` or `%s` but was `%s`\",\n                    A2A_ENDPOINT_TYPE_URL, A2A_ENDPOINT_TYPE_SERVICE, getRegistrationType()));\n        }\n    }\n    \n    protected void fillDefaultRegistrationType() {\n        if (StringUtils.isEmpty(getRegistrationType())) {\n            setRegistrationType(A2A_ENDPOINT_TYPE_URL);\n        }\n    }\n    \n    public String getAgentCard() {\n        return agentCard;\n    }\n    \n    public void setAgentCard(String agentCard) {","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/form/a2a/admin/AgentCardForm.java#L39-L75","documentation":"Thrown by AgentValidationUtils.validateProtocolVersion when protocolVersion is null, empty, or longer than 64 characters. After this length check passes, a separate printable-ASCII check (validatePrintableAscii) enforces characters in 0x21-0x7E (no spaces). This throw at line 148 is specifically the null/empty/over-length gate.","triggerScenarios":"Omitting protocolVersion in a resolve filter (RadModelValidator.validateResolveFilter line 223) or call interface (validateCallInterface line 340), sending an empty string, or a version string over 64 chars. Also AgentRuntimeEndpointMapper (line 330) when building runtime endpoints.","commonSituations":"A form field left unset so it deserializes to null; sending \"\" to 'clear' a value instead of omitting the field; a semver-plus-build string that grows beyond 64 chars; JSON null vs absent field confusion.","solutions":["Provide a non-empty protocolVersion <=64 printable characters (e.g. '1.0.0', '2024.1').","Distinguish 'absent' from 'empty': omit the field rather than sending an empty string when not required.","If the field is optional in your flow, skip calling validateProtocolVersion when it is null."],"exampleFix":"// before\nfilter.setProtocolVersion(\"\");\n// after\nfilter.setProtocolVersion(\"1.2.0\");","handlingStrategy":"validation","validationCode":"if (protocolVersion == null || protocolVersion.isEmpty()\n        || protocolVersion.length() > 64) {\n    throw new IllegalArgumentException(\"Invalid protocolVersion\");\n}","typeGuard":"static boolean isValidProtocolVersionLength(String s) {\n    return s != null && !s.isEmpty() && s.length() <= 64\n        && s.chars().allMatch(c -> c >= 0x21 && c <= 0x7E);\n}","tryCatchPattern":"try {\n    AgentValidationUtils.validateProtocolVersion(protocolVersion);\n} catch (IllegalArgumentException e) {\n    // return 400, field 'protocolVersion'\n}","preventionTips":["Distinguish absent (omit field) from empty string.","Pre-validate length and printable-ASCII before submission."],"tags":["ai-agent","validation","protocol-version","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}