alibaba/nacos · error · NacosApiException

INVALID_PARAM

INVALID_PARAM

Error message

parameters `agentCard` can't be null

What it means

Thrown by the ReleaseAgentCard gRPC handler when the ReleaseAgentCardRequest carries a null `agentCard`. The agent card is the core payload for releasing (publishing) an A2A agent, so it cannot be absent. Returns INVALID_PARAM with PARAMETER_MISSING detail.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/remote/handler/a2a/ReleaseAgentCardRequestHandler.java:84

        throws NacosException {
        AgentRequestUtil.fillNamespaceId(request);
        ReleaseAgentCardResponse response = new ReleaseAgentCardResponse();
        try {
            validateRequest(request);
            doHandler(request, meta);
            return response;
        } catch (NacosException e) {
            response.setErrorInfo(e.getErrCode(), e.getErrMsg());
            LOGGER.error("[{}] Release agent card {} error: {}", meta.getConnectionId(),
                null == request.getAgentCard() ? null : JacksonUtils.toJson(request.getAgentCard()),
                e.getErrMsg());
        }
        return response;
    }
    
    private void validateRequest(ReleaseAgentCardRequest request) throws NacosApiException {
        if (null == request.getAgentCard()) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `agentCard` can't be null");
        }
        AgentRequestUtil.validateAgentCard(request.getAgentCard());
    }
    
    private void doHandler(ReleaseAgentCardRequest request, RequestMeta meta)
        throws NacosException {
        String namespaceId = request.getNamespaceId();
        AgentCard agentCard = request.getAgentCard();
        LOGGER.info("Release new agent {}, version {} into namespaceId {} from connectionId {}.",
            agentCard.getName(),
            agentCard.getVersion(), namespaceId, meta.getConnectionId());
        a2aServerOperationService.releaseAgent(agentCard, namespaceId,
            request.getRegistrationType(), request.isSetAsLatest());
        LOGGER.info("AgentCard {} version {} released.", agentCard.getName(),
            agentCard.getVersion());
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set a fully populated AgentCard on the request before sending (name, version, etc.).
2. Add a client-side null check on request.getAgentCard() before the gRPC call.
3. Use a factory method that requires the AgentCard argument so the request cannot be built without it.

Example fix

// before
ReleaseAgentCardRequest req = new ReleaseAgentCardRequest();
req.setNamespaceId("public"); // agentCard never set -> error

// after
ReleaseAgentCardRequest req = new ReleaseAgentCardRequest();
req.setAgentCard(buildCard());

Objects.requireNonNull(request.getAgentCard(), "agentCard");
AgentRequestUtil.validateAgentCard(request.getAgentCard());

boolean hasCard(ReleaseAgentCardRequest r) {
    return r != null && r.getAgentCard() != null;
}

When it happens

Trigger: Sending a ReleaseAgentCardRequest over gRPC where getAgentCard() is null. Validation happens first in validateRequest(); deeper field validation (AgentRequestUtil.validateAgentCard) runs only after the null check passes.

Common situations: Client builds the request envelope but forgets to attach the AgentCard; a JSON mapping omits the agentCard field; conditional code path skips card construction.

Related errors

• agentCard must be a JSON object
• 10000
• PARAMETER_MISSING
• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISSING

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