alibaba/nacos · error · IllegalArgumentException

Request parameter `agentSpecCard` is invalid and cannot be…

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.

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…
• Request parameter `name` should not be null or empty.
• Required parameter `agentSpecCard.name` is not present.
• 10000
• 10000

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

Appendix: 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)