{"record":{"id":"061e523475070e29","repo":"alibaba/nacos","slug":"agent-version-storage-field-must-be-a-string","errorCode":null,"errorMessage":"Agent Version storage {field} must be a string","messagePattern":"Agent Version storage (.+?) must be a string","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":213,"sourceCode":"            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)) {\n            if (parser.nextToken() == null) {\n                throw new IllegalArgumentException(\n                    \"Agent Version storage descriptor JSON must not be empty\");","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L195-L231","documentation":"During JSON-shape validation, a text field's JSON value is not a string (for example provider given a number, boolean, object, or array). The serializer type-checks each text field before typed binding so the error message names the field.","triggerScenarios":"deserialize() of JSON like {\"provider\":1}, {\"key\":true}, {\"contentDigest\":{}}, or {\"mediaType\":[]}. A bad writer emitting the wrong JSON type triggers it.","commonSituations":"A hand-edited JSON with the wrong value type; a custom writer that serializes a number where a string is expected.","solutions":["Ensure provider/key/keyFormat/agentNameCodec/contentDigest/mediaType are JSON strings in the stored column","Re-publish the version to regenerate a correctly typed descriptor"],"exampleFix":"// before\n{\"provider\":1,...}\n// after\n{\"provider\":\"nacos_config\",...}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    AgentVersionStorageDescriptorSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    throw new NacosException(NacosException.SERVER_ERROR, \"Storage descriptor field type invalid\", e);\n}","preventionTips":["Always produce descriptors via AgentVersionStorageDescriptorSerializer.serialize so field types are correct","Never hand-craft the JSON with numeric values for string fields"],"tags":["java","nacos","ai-agent","validation","json","type-mismatch","storage-descriptor"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}