{"record":{"id":"4521718558a60f0f","repo":"alibaba/nacos","slug":"request-parameter-agentspeccard-is-invalid-and-c","errorCode":null,"errorMessage":"Request parameter `agentSpecCard` is invalid and cannot be parsed.","messagePattern":"Request parameter `agentSpecCard` is invalid and cannot be parsed\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"auth/src/main/java/com/alibaba/nacos/auth/parser/http/AgentSpecCardHttpResourceParser.java","lineNumber":45,"sourceCode":" *\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":27,"sourceCodeEnd":55,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/auth/src/main/java/com/alibaba/nacos/auth/parser/http/AgentSpecCardHttpResourceParser.java#L27-L55","documentation":"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.","triggerScenarios":"Submitting agentSpecCard with malformed JSON, wrong structure, or a field type that does not match AgentSpec.","commonSituations":"Hand-edited JSON with a trailing comma or unquoted key; sending an older/newer schema than the server expects; encoding issues corrupting the payload.","solutions":["Validate the JSON locally with the same AgentSpec model before sending.","Match the AgentSpec schema version expected by the server (consult specs/en/ai/agentspec-spec.md).","Send the payload as UTF-8 and ensure it is not double-encoded."],"exampleFix":"// before\nagentSpecCard='{name: my-agent}'  // unquoted keys -> JSON parse error -> 556\n\n// after\nagentSpecCard='{\"name\":\"my-agent\"}'  // valid JSON","handlingStrategy":"validation","validationCode":"try {\n    JacksonUtils.toObj(agentSpecCard, AgentSpec.class);\n} catch (NacosDeserializationException e) {\n    return Result.failure(\"agentSpecCard JSON is invalid: \" + e.getMessage());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate JSON locally against the AgentSpec model before sending.","Match the AgentSpec schema version the server expects.","Send the payload as UTF-8 to avoid encoding corruption."],"tags":["ai","agentspec","auth","http","json","deserialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}