{"record":{"id":"a9156843319af862","repo":"alibaba/nacos","slug":"20002-a91568","errorCode":"20002","errorMessage":"agentCard is invalid. Can't be parsed.","messagePattern":"agentCard is invalid\\. Can't be parsed\\.","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/utils/AgentRequestUtil.java","lineNumber":69,"sourceCode":"     *\n     * @param agentCardForm agent card request.\n     * @return agent card\n     * @throws NacosApiException if parse failed or request parameter is conflicted.\n     */\n    public static AgentCard parseAgentCard(AgentCardForm agentCardForm) throws NacosApiException {\n        try {\n            AgentCard result =\n                JacksonUtils.toObj(agentCardForm.getAgentCard(), new TypeReference<>() {\n                });\n            normalizeAgentCard(result);\n            validateAgentCard(result);\n            return result;\n        } catch (NacosDeserializationException e) {\n            LOGGER.error(\n                String.format(\"Deserialize %s from %s failed, \", AgentCard.class.getSimpleName(),\n                    agentCardForm.getAgentCard()),\n                e);\n            throw new NacosApiException(NacosApiException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"agentCard is invalid. Can't be parsed.\");\n        }\n    }\n    \n    /**\n     * Validate agent card is legal.\n     *\n     * @param agentCard agent card\n     * @throws NacosApiException if agent card is illegal.\n     */\n    public static void validateAgentCard(AgentCard agentCard) throws NacosApiException {\n        validateAgentCardField(\"name\", agentCard.getName());\n        validateAgentCardField(\"version\", agentCard.getVersion());\n        normalizeAgentCard(agentCard);\n        boolean hasLegacyRequiredFields = isLegacyAgentCard(agentCard);\n        boolean hasV1RequiredFields = isV1AgentCard(agentCard);\n        if (!hasLegacyRequiredFields && !hasV1RequiredFields) {","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/utils/AgentRequestUtil.java#L51-L87","documentation":"Thrown by AgentRequestUtil.parseAgentCard when JacksonUtils.toObj raises a NacosDeserializationException while parsing the agentCard string from AgentCardForm into an AgentCard (A2A agent card). This means the supplied JSON is malformed or does not match the AgentCard schema enough to deserialize. PARAMETER_VALIDATE_ERROR (code 20002, HTTP 400). Note: only deserialization failures are caught here — semantic validation failures are thrown separately by validateAgentCard.","triggerScenarios":"POST/PUT an A2A agent with an agentCard field that is not valid JSON, has wrong types (e.g. supportedInterfaces as a string instead of array), trailing commas, encoding issues, or a payload built by string concatenation rather than a JSON serializer.","commonSituations":"Hand-written JSON typos; copy-pasting a partial card; client sending a YAML or form-encoded body in the agentCard field; version skew where the client's AgentCard shape differs from the server's model.","solutions":["Validate the agentCard string with a JSON parser and the AgentCard schema on the client before sending.","Build the payload with the same Jackson AgentCard model the server uses, then serialize — avoid hand-writing JSON.","Ensure the field is well-formed UTF-8 JSON with correct types (arrays for lists, strings for scalars)."],"exampleFix":"// before: malformed JSON in agentCard form field\nform.setAgentCard('{\"name\":\"a\",\"version\":1.0,}')  // trailing comma, version not string\n\n// after: serialize from the model\nAgentCard card = new AgentCard();\ncard.setName(\"a\");\ncard.setVersion(\"1.0.0\");\nform.setAgentCard(JacksonUtils.toJson(card));","handlingStrategy":"validation","validationCode":"// Validate JSON + shape before sending\ntry {\n    JsonNode node = objectMapper.readTree(form.getAgentCard());\n    if (!node.isObject()) throw new IllegalArgumentException(\"agentCard must be a JSON object\");\n    if (node.has(\"version\") && !node.get(\"version\").isTextual()) {\n        throw new IllegalArgumentException(\"agentCard.version must be a string\");\n    }\n} catch (JsonProcessingException e) {\n    throw new IllegalArgumentException(\"agentCard is not valid JSON\", e);\n}","typeGuard":"static boolean isParsableAgentCard(String json, ObjectMapper mapper) {\n    try { mapper.readValue(json, AgentCard.class); return true; }\n    catch (Exception e) { return false; }\n}","tryCatchPattern":"try {\n    AgentRequestUtil.parseAgentCard(form);\n} catch (NacosApiException e) {\n    if (e.getErrorCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()\n        && e.getMessage().contains(\"agentCard is invalid\")) {\n        // surface a field-level error to the UI / log the raw payload for debugging\n        throw new AgentCardMalformedException(form.getAgentCard());\n    }\n    throw e;\n}","preventionTips":["Serialize AgentCard from the model object rather than hand-writing JSON.","Validate the JSON parses and matches the schema before submit.","Keep the client's AgentCard model version-aligned with the server."],"tags":["a2a","agent","validation","ai-registry","deserialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}