alibaba/nacos · error · IllegalArgumentException

20002

20002

Error message

Unsupported Agent orderBy: %s

What it means

Thrown by AgentValidationUtils.validateTransport when the transport token is null, longer than 64 chars, or fails [0-9A-Za-z+-]{1,64}. A transport token is 1-64 characters drawn from alphanumerics, '+', or '-' only. Unlike protocol, the transport pattern allows '+' and '-' anywhere and has no 'must start with alphanumeric' rule, but rejects underscore, space, and other symbols.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agent/admin/AgentListForm.java:48

 * @author Nacos
 */
public class AgentListForm implements NacosForm {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    private String namespaceId;
    
    private String agentName;
    
    private String orderBy;
    
    @Override
    public void validate() throws NacosApiException {
        namespaceId = NamespaceUtil.processNamespaceParameter(namespaceId);
        AgentValidationUtils.validateNamespaceId(namespaceId);
        if (StringUtils.isNotBlank(orderBy) && !"download_count".equals(orderBy)) {
            throw new IllegalArgumentException("Unsupported Agent orderBy: " + orderBy);
        }
    }
    
    public String getNamespaceId() {
        return namespaceId;
    }
    
    public void setNamespaceId(String namespaceId) {
        this.namespaceId = namespaceId;
    }
    
    public String getAgentName() {
        return agentName;
    }
    
    public void setAgentName(String agentName) {
        this.agentName = agentName;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use a token of [0-9A-Za-z+-] only, e.g. 'grpc', 'http2', 'JSON-RPC-2.0', 'SSE'.
2. Confirm whether the field expects a transport token vs a URI scheme and set it accordingly.
3. Trim and null-check transport before binding the Endpoint.

Example fix

// before
endpoint.setTransport("grpc_web");
// after
endpoint.setTransport("grpc-web");

if (transport == null || transport.length() > 64
        || !transport.matches("^[0-9A-Za-z+-]{1,64}$")) {
    throw new IllegalArgumentException("Invalid transport");
}

static boolean isValidTransport(String s) {
    return s != null && s.length() <= 64
        && s.matches("^[0-9A-Za-z+-]{1,64}$");
}

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

When it happens

Trigger: Registering/canonicalizing an Endpoint whose transport is null or uses underscores (e.g. 'grpc_web'), spaces, or >64 chars. Callers: EndpointCanonicalizer.canonicalize (line 63), EndpointNaturalKey.of (line 91), RadModelValidator.validateTransports (line 513), AgentRuntimeEndpointMapper (line 183).

Common situations: Reusing an internal transport identifier that contains underscores; lowercase/uppercase inconsistency (both are allowed, but teams may expect normalization); sending the scheme ('https') where the transport token is expected.

Related errors

• 20002
• 10000
• 10000
• endpointSourceOrder must contain 1 or 2 sources
• Duplicate Endpoint source: {source}

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