alibaba/nacos · error · IllegalArgumentException

Required parameter `agentSpecCard.name` is not present.

Error message

Required parameter `agentSpecCard.name` is not present.

What it means

Third guard in AgentSpecCardHttpResourceParser: the JSON parsed successfully but the resulting AgentSpec has a null/blank name. Authorization requires a concrete resource name, so the parser refuses the request.

Source

Thrown at auth/src/main/java/com/alibaba/nacos/auth/parser/http/AgentSpecCardHttpResourceParser.java:49

    
    private static final String AGENT_SPEC_CARD_PARAM = "agentSpecCard";
    
    @Override
    protected String getResourceName(HttpServletRequest request) {
        String agentSpecCard = request.getParameter(AGENT_SPEC_CARD_PARAM);
        if (StringUtils.isBlank(agentSpecCard)) {
            throw new IllegalArgumentException(
                "Request parameter `agentSpecCard` should not be null or empty.");
        }
        AgentSpec agentSpec;
        try {
            agentSpec = JacksonUtils.toObj(agentSpecCard, AgentSpec.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException(
                "Request parameter `agentSpecCard` is invalid and cannot be parsed.", e);
        }
        if (agentSpec == null || StringUtils.isBlank(agentSpec.getName())) {
            throw new IllegalArgumentException(
                "Required parameter `agentSpecCard.name` is not present.");
        }
        return agentSpec.getName();
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure the agentSpecCard JSON contains a non-blank 'name' field.
Validate the AgentSpec object's name client-side before serializing.

Example fix

// before
agentSpecCard='{"description":"demo"}'  // no name -> 557

// after
agentSpecCard='{"name":"my-agent","description":"demo"}'

Defensive patterns

Strategy: validation

Validate before calling

AgentSpec spec = JacksonUtils.toObj(agentSpecCard, AgentSpec.class);
if (spec == null || StringUtils.isBlank(spec.getName())) {
    throw new IllegalArgumentException("agentSpecCard.name is required");
}

Prevention

Always populate the name field on AgentSpec payloads.
Validate the model client-side before serializing to JSON.

When it happens

Trigger: Submitting an agentSpecCard JSON that omits the name field or sets it to empty.

Common situations: Template payload missing the name property; building AgentSpec from optional fields where name was never populated.

Related errors

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