alibaba/nacos · error · IllegalArgumentException

Request parameter `agentSpecCard` is invalid and cannot be p

Error message

Request parameter `agentSpecCard` is invalid and cannot be parsed.

What it means

Second guard in AgentSpecCardHttpResourceParser: the agentSpecCard string is present but cannot be deserialized into AgentSpec (Jackson throws NacosDeserializationException). The parser wraps it in IllegalArgumentException to surface malformed JSON at the auth boundary.

Source

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

 *
 * @author xiweng.yy
 */
public class AgentSpecCardHttpResourceParser extends AiHttpResourceParser {
    
    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

1. Validate the JSON locally with the same AgentSpec model before sending.
2. Match the AgentSpec schema version expected by the server (consult specs/en/ai/agentspec-spec.md).
3. Send the payload as UTF-8 and ensure it is not double-encoded.

Example fix

// before
agentSpecCard='{name: my-agent}'  // unquoted keys -> JSON parse error -> 556

// after
agentSpecCard='{"name":"my-agent"}'  // valid JSON

try {
    JacksonUtils.toObj(agentSpecCard, AgentSpec.class);
} catch (NacosDeserializationException e) {
    return Result.failure("agentSpecCard JSON is invalid: " + e.getMessage());
}

When it happens

Trigger: Submitting agentSpecCard with malformed JSON, wrong structure, or a field type that does not match AgentSpec.

Common situations: Hand-edited JSON with a trailing comma or unquoted key; sending an older/newer schema than the server expects; encoding issues corrupting the payload.

Related errors

• Request parameter `agentSpecCard` should not be null or empt
• Required parameter `agentSpecCard.name` is not present.
• Request parameter `name` should not be null or empty.
• 10000
• 20002

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