alibaba/nacos · error · NacosApiException

10000

10000

Error message

Request parameter `agentCard` should not be `null` or empty.

What it means

Thrown by AgentValidationUtils.validateProtocol when the protocol token is null, longer than 32 chars, or fails the pattern [A-Za-z0-9][A-Za-z0-9-]{0,31}. A valid protocol starts with an alphanumeric character and continues with alphanumerics or dashes, 1-32 characters total. Underscores, leading dashes, spaces, or symbols are rejected.

Source

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

/**
 * Agent Card Form request.
 *
 * @author xiweng.yy
 */
public class AgentCardForm extends AgentForm {
    
    @Serial
    private static final long serialVersionUID = 8361628138801381818L;
    
    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()));
        }
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use a token like 'A2A-v1', 'mcp', 'grpc', or 'http' (alphanumeric start, dashes only afterwards, <=32 chars).
2. Trim and null-check the protocol field before request binding.
3. Centralize protocol constants instead of building them dynamically from user input.

Example fix

// before
form.setProtocol("a2a_rpc");
// after
form.setProtocol("a2a-v1");

if (protocol == null || protocol.length() > 32
        || !protocol.matches("^[A-Za-z0-9][A-Za-z0-9-]{0,31}$")) {
    throw new IllegalArgumentException("Invalid protocol");
}

static boolean isValidProtocol(String s) {
    return s != null && s.length() <= 32
        && s.matches("^[A-Za-z0-9][A-Za-z0-9-]{0,31}$");
}

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

When it happens

Trigger: Registering a RAD catalog or endpoint with protocol set to an underscore form ("a2a_rpc"), a leading dash ("-a2a"), null, empty, or >32 chars. Callers include RadModelValidator.validateProtocols, EndpointNaturalKey.of, AgentRuntimeEndpointForm.validate (line 38), RuntimeEndpointRevision, and RadServiceNameComposer.

Common situations: Developers reusing snake_case protocol identifiers from another system; copy-pasting a protocol name with trailing whitespace; mismatch between a client's protocol string and the allowed token grammar; version suffixes appended with illegal characters.

Related errors

• 20002
• 10000
• 20002
• 20002
• 10000

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