alibaba/nacos · warning · NacosApiException

INVALID_PARAM

INVALID_PARAM

Error message

parameter `type` should be %s or %s, but was %s

What it means

Thrown by the default branch of the type switch in AgentEndpointRequestHandler.handle() (legacy/non-canonical A2A path) when request.getType() is neither REGISTER_ENDPOINT ('registerEndpoint') nor DE_REGISTER_ENDPOINT ('deregisterEndpoint'). Mapped to PARAMETER_VALIDATE_ERROR detail code under an INVALID_PARAM top-level code; caught and placed into the AgentEndpointResponse error info. Available since 3.1.0.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/remote/handler/a2a/AgentEndpointRequestHandler.java:116

                handleCanonical(request, meta);
                return response;
            }
            Instance instance = transferInstance(request);
            String serviceName =
                agentIdCodecHolder.encode(request.getAgentName()) + "::"
                    + request.getEndpoint().getVersion();
            Service service =
                Service.newService(request.getNamespaceId(), Constants.Agent.AGENT_ENDPOINT_GROUP,
                    serviceName);
            switch (request.getType()) {
                case AiRemoteConstants.REGISTER_ENDPOINT:
                    doRegisterEndpoint(service, instance, meta);
                    break;
                case AiRemoteConstants.DE_REGISTER_ENDPOINT:
                    doDeregisterEndpoint(service, instance, meta);
                    break;
                default:
                    throw new NacosApiException(NacosException.INVALID_PARAM,
                        ErrorCode.PARAMETER_VALIDATE_ERROR,
                        String.format("parameter `type` should be %s or %s, but was %s",
                            AiRemoteConstants.REGISTER_ENDPOINT,
                            AiRemoteConstants.DE_REGISTER_ENDPOINT, request.getType()));
            }
        } catch (NacosApiException e) {
            response.setErrorInfo(e.getErrCode(), e.getErrMsg());
            LOGGER.error("[{}] Register agent endpoint to agent {} error: {}",
                meta.getConnectionId(),
                request.getAgentName(), e.getErrMsg());
        }
        return response;
    }
    
    private void handleCanonical(AgentEndpointRequest request, RequestMeta meta)
        throws NacosException {
        switch (request.getType()) {
            case AiRemoteConstants.REGISTER_ENDPOINT:

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set request.setType to AiRemoteConstants.REGISTER_ENDPOINT or AiRemoteConstants.DE_REGISTER_ENDPOINT.
2. Use the SDK typed constants instead of hand-coded strings.
3. Confirm you are calling the single endpoint handler and not the batch handler.

Example fix

// before
req.setType("register");

// after
req.setType(AiRemoteConstants.REGISTER_ENDPOINT);

String t = request.getType();
if (!AiRemoteConstants.REGISTER_ENDPOINT.equals(t)
    && !AiRemoteConstants.DE_REGISTER_ENDPOINT.equals(t)) {
    throw new IllegalArgumentException("AgentEndpointRequest.type must be registerEndpoint or deregisterEndpoint");
}

AgentEndpointResponse resp = handler.handle(request, meta);
if (resp.getErrCode() != 0 && resp.getErrMsg().contains("type should")) {
    // fix the type constant and retry
}

When it happens

Trigger: A gRPC AgentEndpointRequest whose type is null, empty, or any value other than the two recognized constants, AND the compatibility mode is not CANONICAL (the canonical path has its own equivalent check).

Common situations: Client sends a raw string type that is mistyped; client leaves type null; version skew in the A2A protocol constants; sending BATCH_REGISTER_ENDPOINT to the single-endpoint handler.

Related errors

• INVALID_PARAM
• PARAMETER_MISSING
• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISSING
• 10000

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