{"record":{"id":"3d17533bce839838","repo":"alibaba/nacos","slug":"agent-version-storage-field-must-be-an-integer","errorCode":null,"errorMessage":"Agent Version storage {field} must be an integer","messagePattern":"Agent Version storage (.+?) must be an integer","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":222,"sourceCode":"    \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\");\n            }\n            parser.skipChildren();\n            if (parser.nextToken() != null) {\n                throw new IllegalArgumentException(\n                    \"Agent Version storage descriptor must contain one JSON value\");\n            }\n        } catch (IOException e) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage descriptor\", e);\n        }","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L204-L240","documentation":"During JSON-shape validation, schemaVersion or size is not an integer JSON token. Only Byte/Short/Integer/Long values are accepted; JSON floats (1.0, 128.5) and strings/booleans are rejected, even if they look numeric.","triggerScenarios":"deserialize() of JSON like {\"schemaVersion\":1.0}, {\"size\":\"large\"}, or {\"size\":128.5}.","commonSituations":"JSON written with a float where an integer is expected; a string-encoded size; a writer that emits numbers as strings.","solutions":["Write schemaVersion and size as JSON integers (no decimal point, no quotes)","Re-publish the version to regenerate a correctly typed descriptor"],"exampleFix":"// before\n{\"schemaVersion\":1.0,\"size\":\"128\"}\n// after\n{\"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, \"schemaVersion/size must be JSON integers\", e);\n}","preventionTips":["Serialize schemaVersion and size as JSON integers, never floats or strings","Generate descriptors through the serializer to guarantee integer types"],"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"}