{"record":{"id":"a5b7bc714addb4df","repo":"alibaba/nacos","slug":"10000-a5b7bc","errorCode":"10000","errorMessage":"Request parameter `agentSpecCard` should not be `null` or empty.","messagePattern":"Request parameter `agentSpecCard` should not be `null` or empty\\.","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecDetailForm.java","lineNumber":47,"sourceCode":" * @author nacos\n */\npublic class AgentSpecDetailForm extends AgentSpecForm {\n    \n    @Serial\n    private static final long serialVersionUID = 1L;\n    \n    /**\n     * AgentSpec card JSON string, contains complete AgentSpec information.\n     */\n    private String agentSpecCard;\n    \n    @Override\n    public void validate() throws NacosApiException {\n        fillDefaultNamespaceId();\n        // For create/detail, agentSpecName is optional (can be in agentSpecCard)\n        // Only agentSpecCard is required\n        if (StringUtils.isEmpty(agentSpecCard)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Request parameter `agentSpecCard` should not be `null` or empty.\");\n        }\n    }\n    \n    public String getAgentSpecCard() {\n        return agentSpecCard;\n    }\n    \n    public void setAgentSpecCard(String agentSpecCard) {\n        this.agentSpecCard = agentSpecCard;\n    }\n}\n","sourceCodeStart":29,"sourceCodeEnd":60,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecDetailForm.java#L29-L60","documentation":"Thrown by AgentValidationUtils.validateEndpointMetadata when a metadata value is null or longer than 256 code points (MAX_METADATA_VALUE_LENGTH). The check uses codePointCount, so supplementary-plane characters (emoji etc.) count as one code point but multi-byte. Keys are validated first, so the offending key is named in the message.","triggerScenarios":"Putting a null value or a value longer than 256 code points into Endpoint metadata during canonicalization/runtime mapping. For example embedding a long JSON blob or URL as a metadata value.","commonSituations":"Storing a serialized object, base64 payload, or full URL+token as a metadata value; null values from a map merge where one side lacked the key; emoji-rich values inflating perceived length.","solutions":["Keep each metadata value non-null and <=256 code points.","Move large payloads (certificates, descriptors) out of metadata into a referenced resource.","Sanitize map merges to drop null values before submission."],"exampleFix":"// before\nmeta.put(\"app.config\", hugeJsonBlob); // 600 chars\n// after\nmeta.put(\"app.configRef\", descriptorUri);","handlingStrategy":"validation","validationCode":"for (Map.Entry<String,String> e : metadata.entrySet()) {\n    String v = e.getValue();\n    if (v == null || v.codePointCount(0, v.length()) > 256) {\n        throw new IllegalArgumentException(\"Invalid Endpoint metadata value for key: \" + e.getKey());\n    }\n}","typeGuard":"static boolean isValidMetadataValue(String v) {\n    return v != null && v.codePointCount(0, v.length()) <= 256;\n}","tryCatchPattern":"try {\n    AgentValidationUtils.validateEndpointMetadata(metadata);\n} catch (IllegalArgumentException e) {\n    // return 400, invalid metadata value\n}","preventionTips":["Keep metadata values short; move large payloads to a referenced resource.","Drop null values during map merges."],"tags":["ai-agent","validation","metadata","endpoint","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}