{"record":{"id":"de0ef92d4f3293af","repo":"alibaba/nacos","slug":"10000-de0ef9","errorCode":"10000","errorMessage":"Request parameter `agentSpecName` should not be blank.","messagePattern":"Request parameter `agentSpecName` should not be blank\\.","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecBizTagsUpdateForm.java","lineNumber":45,"sourceCode":" * AgentSpec biz tags update form.\n *\n * @author nacos\n */\npublic class AgentSpecBizTagsUpdateForm extends AgentSpecForm {\n    \n    @Serial\n    private static final long serialVersionUID = 1L;\n    \n    /**\n     * JSON string: [\"tag1\",\"tag2\"].\n     */\n    private String bizTags;\n    \n    @Override\n    public void validate() throws NacosApiException {\n        fillDefaultNamespaceId();\n        if (StringUtils.isBlank(getAgentSpecName())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Request parameter `agentSpecName` should not be blank.\");\n        }\n    }\n    \n    public String getBizTags() {\n        return bizTags;\n    }\n    \n    public void setBizTags(String bizTags) {\n        this.bizTags = bizTags;\n    }\n}\n","sourceCodeStart":27,"sourceCodeEnd":58,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecBizTagsUpdateForm.java#L27-L58","documentation":"Thrown by AgentValidationUtils.validateEndpointMetadata when a metadata key is null, empty, longer than 64 code points (MAX_METADATA_KEY_LENGTH), or reserved. Reserved keys are 'preserved.heart.beat.interval', 'preserved.heart.beat.timeout', 'preserved.ip.delete.timeout', and any key starting with '__nacos.agent.endpoint.'.","triggerScenarios":"Putting a reserved key (e.g. 'preserved.heart.beat.interval') into Endpoint metadata, or a key that is null/empty/>64 code points, during canonicalization (EndpointCanonicalizer line 77), runtime endpoint mapping, or resolve filter metadataSelector.","commonSituations":"Reusing Nacos naming 'preserved.*' metadata keys inside AI Endpoint metadata (they are naming-instance internals, not allowed here); a merge producing a null key; very long auto-generated keys.","solutions":["Avoid the reserved 'preserved.heart.beat.*', 'preserved.ip.delete.timeout', and '__nacos.agent.endpoint.*' keys.","Ensure every key is non-empty and <=64 code points.","Namespace your own keys with a stable prefix (e.g. 'app.region') to avoid collisions."],"exampleFix":"// before\nmeta.put(\"preserved.heart.beat.interval\", \"5000\");\n// after\nmeta.put(\"app.heartbeat.interval\", \"5000\");","handlingStrategy":"validation","validationCode":"for (Map.Entry<String,String> e : metadata.entrySet()) {\n    String k = e.getKey();\n    if (k == null || k.isEmpty() || k.codePointCount(0, k.length()) > 64\n            || \"preserved.heart.beat.interval\".equals(k)\n            || \"preserved.heart.beat.timeout\".equals(k)\n            || \"preserved.ip.delete.timeout\".equals(k)\n            || k.startsWith(\"__nacos.agent.endpoint.\")) {\n        throw new IllegalArgumentException(\"Invalid Endpoint metadata key: \" + k);\n    }\n}","typeGuard":"static boolean isValidMetadataKey(String k) {\n    return k != null && !k.isEmpty() && k.codePointCount(0, k.length()) <= 64\n        && !\"preserved.heart.beat.interval\".equals(k)\n        && !\"preserved.heart.beat.timeout\".equals(k)\n        && !\"preserved.ip.delete.timeout\".equals(k)\n        && !k.startsWith(\"__nacos.agent.endpoint.\");\n}","tryCatchPattern":"try {\n    AgentValidationUtils.validateEndpointMetadata(metadata);\n} catch (IllegalArgumentException e) {\n    // return 400, invalid metadata key\n}","preventionTips":["Avoid 'preserved.*' and '__nacos.agent.endpoint.*' keys.","Namespace your own keys with a stable prefix."],"tags":["ai-agent","validation","metadata","reserved-key","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}