alibaba/nacos · error · IllegalArgumentException

Request parameter `agentSpecCard` should not be null or empt

Error message

Request parameter `agentSpecCard` should not be null or empty.

What it means

AgentSpecCardHttpResourceParser.getResourceName resolves the authz target from the HTTP 'agentSpecCard' parameter. The first guard rejects a null/blank agentSpecCard string before attempting JSON deserialization, because authorization cannot proceed without a resource name.

Source

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

import com.alibaba.nacos.api.exception.runtime.NacosDeserializationException;
import com.alibaba.nacos.common.utils.JacksonUtils;
import com.alibaba.nacos.common.utils.StringUtils;
import jakarta.servlet.http.HttpServletRequest;

/**
 * AgentSpec HTTP resource parser that resolves the target name from {@code agentSpecCard}.
 *
 * @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. Include a non-blank agentSpecCard JSON payload in the request.
2. Validate the field client-side before submitting the form.
3. Confirm the parameter is sent as form/url-encoded data and not swallowed by content-type mismatch.

Example fix

// before
curl -X POST 'http://nacos:8848/v3/admin/ai/agent/spec'  # no agentSpecCard -> 555

// after
curl -X POST 'http://nacos:8848/v3/admin/ai/agent/spec' \
  --data-urlencode 'agentSpecCard={"name":"my-agent",...}'

String card = request.getParameter("agentSpecCard");
if (StringUtils.isBlank(card)) {
    return Result.failure("agentSpecCard is required");
}

When it happens

Trigger: Calling an AgentSpec HTTP API (create/update via card) without the agentSpecCard form/query parameter, or with a whitespace-only value.

Common situations: Console request missing the agentSpecCard field; curl/script that forgot to attach the JSON body field; form encoding issue stripping the parameter.

Related errors

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

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