{"record":{"id":"696e38a35846ac4b","repo":"alibaba/nacos","slug":"missing-agent-version-storage-field-field","errorCode":null,"errorMessage":"Missing Agent Version storage field: {field}","messagePattern":"Missing Agent Version storage field: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":210,"sourceCode":"    \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(\n                \"Agent Version storage \" + field + \" must be a string\");\n        }\n    }\n    \n    private static void validateJsonInteger(Map<?, ?> root, String field) {\n        Object value = root.get(field);\n        if (!(value instanceof Byte || value instanceof Short || value instanceof Integer\n            || value instanceof Long)) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage \" + field + \" must be an integer\");\n        }\n    }\n    \n    private static void validateSingleJsonValue(String json) {\n        try (JsonParser parser = STRICT_JSON_FACTORY.createParser(json)) {","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L192-L228","documentation":"During JSON-shape validation, a required text field (provider, key, contentDigest, or mediaType) is absent from the JSON object. keyFormat and agentNameCodec are optional and may be omitted.","triggerScenarios":"deserialize() of a JSON object missing one of provider/key/contentDigest/mediaType. For example, deleting the \"key\" field from the stored descriptor.","commonSituations":"A hand-edited JSON with a field removed; a partial JSON document; an older descriptor format missing a now-required field.","solutions":["Include all required fields (provider, key, contentDigest, mediaType, plus schemaVersion and size) in the stored JSON","Re-publish the version to regenerate a complete descriptor","Restore the row from a backup if the original is lost"],"exampleFix":"// before\n{\"key\":\"...\",\"contentDigest\":\"sha256:...\",\"mediaType\":\"...\",\"schemaVersion\":1,\"size\":128}\n// after (provider added)\n{\"provider\":\"nacos_config\",\"key\":\"...\",\"contentDigest\":\"sha256:...\",\"mediaType\":\"...\",\"schemaVersion\":1,\"size\":128}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    AgentVersionStorageDescriptorSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    throw new NacosException(NacosException.SERVER_ERROR, \"Corrupt storage descriptor: \" + e.getMessage(), e);\n}","preventionTips":["Always write complete descriptors via the serializer; never partially edit the stored JSON","Re-publish versions whose stored JSON is missing required fields"],"tags":["java","nacos","ai-agent","validation","json","schema","storage-descriptor"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}