{"record":{"id":"6ffe01d4202caada","repo":"alibaba/nacos","slug":"request-parameter-agentspeccard-should-not-be-nu","errorCode":null,"errorMessage":"Request parameter `agentSpecCard` should not be null or empty.","messagePattern":"Request parameter `agentSpecCard` should not be null or empty\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"auth/src/main/java/com/alibaba/nacos/auth/parser/http/AgentSpecCardHttpResourceParser.java","lineNumber":38,"sourceCode":"import com.alibaba.nacos.api.exception.runtime.NacosDeserializationException;\nimport com.alibaba.nacos.common.utils.JacksonUtils;\nimport com.alibaba.nacos.common.utils.StringUtils;\nimport jakarta.servlet.http.HttpServletRequest;\n\n/**\n * AgentSpec HTTP resource parser that resolves the target name from {@code agentSpecCard}.\n *\n * @author xiweng.yy\n */\npublic class AgentSpecCardHttpResourceParser extends AiHttpResourceParser {\n    \n    private static final String AGENT_SPEC_CARD_PARAM = \"agentSpecCard\";\n    \n    @Override\n    protected String getResourceName(HttpServletRequest request) {\n        String agentSpecCard = request.getParameter(AGENT_SPEC_CARD_PARAM);\n        if (StringUtils.isBlank(agentSpecCard)) {\n            throw new IllegalArgumentException(\n                \"Request parameter `agentSpecCard` should not be null or empty.\");\n        }\n        AgentSpec agentSpec;\n        try {\n            agentSpec = JacksonUtils.toObj(agentSpecCard, AgentSpec.class);\n        } catch (NacosDeserializationException e) {\n            throw new IllegalArgumentException(\n                \"Request parameter `agentSpecCard` is invalid and cannot be parsed.\", e);\n        }\n        if (agentSpec == null || StringUtils.isBlank(agentSpec.getName())) {\n            throw new IllegalArgumentException(\n                \"Required parameter `agentSpecCard.name` is not present.\");\n        }\n        return agentSpec.getName();\n    }\n}\n","sourceCodeStart":20,"sourceCodeEnd":55,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/auth/src/main/java/com/alibaba/nacos/auth/parser/http/AgentSpecCardHttpResourceParser.java#L20-L55","documentation":"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.","triggerScenarios":"Calling an AgentSpec HTTP API (create/update via card) without the agentSpecCard form/query parameter, or with a whitespace-only value.","commonSituations":"Console request missing the agentSpecCard field; curl/script that forgot to attach the JSON body field; form encoding issue stripping the parameter.","solutions":["Include a non-blank agentSpecCard JSON payload in the request.","Validate the field client-side before submitting the form.","Confirm the parameter is sent as form/url-encoded data and not swallowed by content-type mismatch."],"exampleFix":"// before\ncurl -X POST 'http://nacos:8848/v3/admin/ai/agent/spec'  # no agentSpecCard -> 555\n\n// after\ncurl -X POST 'http://nacos:8848/v3/admin/ai/agent/spec' \\\n  --data-urlencode 'agentSpecCard={\"name\":\"my-agent\",...}'","handlingStrategy":"validation","validationCode":"String card = request.getParameter(\"agentSpecCard\");\nif (StringUtils.isBlank(card)) {\n    return Result.failure(\"agentSpecCard is required\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate the agentSpecCard field client-side before submitting.","Ensure the parameter is sent as form/url-encoded data."],"tags":["ai","agentspec","auth","http","validation","parameter"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}