alibaba/nacos · error · NacosApiException

20002

20002

Error message

Required parameter 'registrationType' value should be `%s` or `%s` but was `%s`

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/a2a/admin/AgentCardForm.java:57

    private String agentCard;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        fillDefaultRegistrationType();
        if (StringUtils.isEmpty(agentCard)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Request parameter `agentCard` should not be `null` or empty.");
        }
        validateRegistrationType();
        
    }
    
    protected void validateRegistrationType() throws NacosApiException {
        if (!A2A_ENDPOINT_TYPE_URL.equals(getRegistrationType())
            && !A2A_ENDPOINT_TYPE_SERVICE.equals(
                getRegistrationType())) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                String.format(
                    "Required parameter 'registrationType' value should be `%s` or `%s` but was `%s`",
                    A2A_ENDPOINT_TYPE_URL, A2A_ENDPOINT_TYPE_SERVICE, getRegistrationType()));
        }
    }
    
    protected void fillDefaultRegistrationType() {
        if (StringUtils.isEmpty(getRegistrationType())) {
            setRegistrationType(A2A_ENDPOINT_TYPE_URL);
        }
    }
    
    public String getAgentCard() {
        return agentCard;
    }
    
    public void setAgentCard(String agentCard) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide a non-empty protocolVersion <=64 printable characters (e.g. '1.0.0', '2024.1').
2. Distinguish 'absent' from 'empty': omit the field rather than sending an empty string when not required.
3. If the field is optional in your flow, skip calling validateProtocolVersion when it is null.

Example fix

// before
filter.setProtocolVersion("");
// after
filter.setProtocolVersion("1.2.0");

if (protocolVersion == null || protocolVersion.isEmpty()
        || protocolVersion.length() > 64) {
    throw new IllegalArgumentException("Invalid protocolVersion");
}

static boolean isValidProtocolVersionLength(String s) {
    return s != null && !s.isEmpty() && s.length() <= 64
        && s.chars().allMatch(c -> c >= 0x21 && c <= 0x7E);
}

try {
    AgentValidationUtils.validateProtocolVersion(protocolVersion);
} catch (IllegalArgumentException e) {
    // return 400, field 'protocolVersion'
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 10000
• 20002
• 10000
• 10000
• 20002

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