{"record":{"id":"1731a30ad38a11b4","repo":"alibaba/nacos","slug":"invalid-agent-version-storage-field","errorCode":null,"errorMessage":"Invalid Agent Version storage {field}","messagePattern":"Invalid Agent Version storage (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":195,"sourceCode":"        if (size == null || size < 0 || size > MAX_CONTENT_SIZE) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage size must be between 0 and \" + MAX_CONTENT_SIZE);\n        }\n        if (NACOS_CONFIG_PROVIDER.equals(provider)) {\n            if (!NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {\n                throw new IllegalArgumentException(\"nacos_config keyFormat must be \"\n                    + NACOS_CONFIG_KEY_FORMAT);\n            }\n            if (!RAD_ASCII_AGENT_NAME_CODEC.equals(descriptor.getAgentNameCodec())) {\n                throw new IllegalArgumentException(\"nacos_config agentNameCodec must be \"\n                    + RAD_ASCII_AGENT_NAME_CODEC);\n            }\n        }\n    }\n    \n    private static void validateRequiredText(String field, String value, int maxLength) {\n        if (value == null || value.isEmpty() || value.length() > maxLength) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage \" + field);\n        }\n    }\n    \n    private static void validateOptionalText(String field, String value, int maxLength) {\n        if (value != null) {\n            validateRequiredText(field, value, maxLength);\n        }\n    }\n    \n    private static void validateJsonText(Map<?, ?> root, String field, boolean optional) {\n        if (!root.containsKey(field)) {\n            if (optional) {\n                return;\n            }\n            throw new IllegalArgumentException(\"Missing Agent Version storage field: \" + field);\n        }\n        if (!(root.get(field) instanceof String)) {\n            throw new IllegalArgumentException(","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L177-L213","documentation":"Thrown by validateRequiredText (also reached via validateOptionalText for keyFormat/agentNameCodec when they are non-null): the field value is null, empty, or exceeds its maximum length. Applies to key (max 1024), and to keyFormat/agentNameCodec (max 64) when present.","triggerScenarios":"validate()/serialize() on a descriptor where key is null/empty/over 1024 chars, or keyFormat/agentNameCodec is a non-null empty string or over 64 chars.","commonSituations":"A very deep namespace/agent/version producing a key over 1024 chars; an optional field explicitly set to \"\" instead of null; a truncation bug producing empty strings.","solutions":["Provide a non-empty key within 1024 characters","For optional keyFormat/agentNameCodec, leave them null rather than setting an empty string","Shorten the agent name or version if the storage key overflows the 1024-char limit"],"exampleFix":"// before\ndescriptor.setKey(\"\");\n// after\ndescriptor.setKey(\"namespace:agent-version:agent__Agent__1.0.0.json\");","handlingStrategy":"validation","validationCode":"private static void requireText(String name, String value, int max) {\n    if (value == null || value.isEmpty() || value.length() > max) {\n        throw new IllegalArgumentException(name + \" must be non-empty and <= \" + max);\n    }\n}\nrequireText(\"key\", descriptor.getKey(), 1024);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Leave optional keyFormat/agentNameCodec as null rather than setting them to empty strings","Shorten agent name/version if the storage key exceeds 1024 chars"],"tags":["java","nacos","ai-agent","validation","length-limit","storage-descriptor"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}