{"record":{"id":"8cfba9b6025e300b","repo":"alibaba/nacos","slug":"must-be-an-integer","errorCode":null,"errorMessage":"{} must be an integer","messagePattern":"(.+?) must be an integer","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java","lineNumber":389,"sourceCode":"    }\n    \n    private static void validateRequiredJsonText(Map<?, ?> object, String field) {\n        if (!(object.get(field) instanceof String)) {\n            throw new IllegalArgumentException(field + \" must be a string\");\n        }\n    }\n    \n    private static void validateOptionalJsonText(Map<?, ?> object, String field) {\n        if (object.containsKey(field) && !(object.get(field) instanceof String)) {\n            throw new IllegalArgumentException(field + \" must be a string\");\n        }\n    }\n    \n    private static void validateJsonInteger(Map<?, ?> object, String field) {\n        Object value = object.get(field);\n        if (!(value instanceof Byte || value instanceof Short || value instanceof Integer\n            || value instanceof Long)) {\n            throw new IllegalArgumentException(field + \" must be an integer\");\n        }\n    }\n    \n    private static void rejectUnknownFields(Map<?, ?> object, Set<String> allowedFields,\n        String objectName) {\n        for (Object field : object.keySet()) {\n            if (!allowedFields.contains(field)) {\n                throw new IllegalArgumentException(\n                    \"Unknown \" + objectName + \" field: \" + field);\n            }\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(\"AgentResourceExt JSON must not be empty\");\n            }","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java#L371-L407","documentation":"The root 'schemaVersion' field in ai_resource.ext JSON must be an integer. The validateJsonInteger helper (line 388) throws this when schemaVersion is present but is not an integer type — it rejects floats, strings, booleans, and objects. Only Byte, Short, Integer, and Long are accepted (Jackson deserializes small numbers as Integer).","triggerScenarios":"Deserializing ai_resource.ext where 'schemaVersion' is a float (1.0), a string (\"1\"), or omitted entirely (which would fail the earlier unknown-field or required check).","commonSituations":"JSON producers that always serialize numbers as floats; hand-editing and quoting the version number; schema generators that emit schemaVersion as a string.","solutions":["Ensure schemaVersion is an unquoted JSON integer, e.g. 1 not 1.0 or \"1\".","The current expected value is AgentResourceExt.SCHEMA_VERSION (currently 1).","Audit the producer's number serialization to use integer types for this field."],"exampleFix":"// before\n{\"schemaVersion\":1.0}\n// after\n{\"schemaVersion\":1}","handlingStrategy":"validation","validationCode":"Object sv = root.get(\"schemaVersion\");\nif (!(sv instanceof Integer) && !(sv instanceof Long) && !(sv instanceof Short) && !(sv instanceof Byte)) {\n    throw new IllegalArgumentException(\"schemaVersion must be an integer\");\n}","typeGuard":"public static boolean isJsonInteger(Object value) {\n    return value instanceof Byte || value instanceof Short\n        || value instanceof Integer || value instanceof Long;\n}","tryCatchPattern":"try {\n    AgentResourceExtSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"schemaVersion\") && e.getMessage().contains(\"integer\")) {\n        // cast or regenerate the schemaVersion as an integer\n    }\n    throw e;\n}","preventionTips":["Always emit schemaVersion as an unquoted JSON integer.","Ensure the current schemaVersion value matches AgentResourceExt.SCHEMA_VERSION.","Audit JSON producers that may serialize numbers as floats or strings."],"tags":["validation","ai-agent","json-schema","serialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}