{"record":{"id":"5270cb43d5cf4a68","repo":"alibaba/nacos","slug":"fieldname-must-be-a-non-negative-integer","errorCode":null,"errorMessage":"{fieldName} must be a non-negative integer","messagePattern":"(.+?) must be a non-negative integer","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":651,"sourceCode":"            throw new IllegalArgumentException(\"Invalid \" + fieldName + \": \" + value, e);\n        }\n    }\n    \n    private static void validateRequiredLength(String value, int maximum, String fieldName) {\n        if (value == null || value.isEmpty() || codePointLength(value) > maximum) {\n            throw new IllegalArgumentException(\"Invalid \" + fieldName + \": \" + value);\n        }\n    }\n    \n    private static void validateOptionalLength(String value, int maximum, String fieldName) {\n        if (value != null && codePointLength(value) > maximum) {\n            throw new IllegalArgumentException(\"Invalid \" + fieldName + \": exceeds \" + maximum);\n        }\n    }\n    \n    private static void validateEpochMillis(Long value, String fieldName) {\n        if (value == null || value < 0) {\n            throw new IllegalArgumentException(fieldName + \" must be a non-negative integer\");\n        }\n    }\n    \n    private static int codePointLength(String value) {\n        return value.codePointCount(0, value.length());\n    }\n    \n    private static <T> T requireNonNull(T value, String fieldName) {\n        if (value == null) {\n            throw new IllegalArgumentException(fieldName + \" must not be null\");\n        }\n        return value;\n    }\n}\n","sourceCodeStart":633,"sourceCodeEnd":666,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L633-L666","documentation":"Thrown by validateEpochMillis when a timestamp field is null or a negative Long. The fields guarded are the Agent epoch millis: metaVersion, createTime, updateTime (via validateAgentFields), and lastUpdatedTime on a RuntimeEndpointSnapshotItem (via validateRuntimeEndpointSnapshotItem). All are expected to be non-negative epoch-millisecond values; the validator does not impose an upper bound, only non-null and >= 0.","triggerScenarios":"Agent publish/update or runtime snapshot push where one of metaVersion/createTime/updateTime/lastUpdatedTime is null or < 0. E.g. setting lastUpdatedTime to -1 as a sentinel, or leaving metaVersion null.","commonSituations":"Using -1 or 0-with-negative-sign as a 'not set' sentinel instead of computing a real timestamp; a clock skew/underflow producing a negative value; omitting a server-managed field in a payload that still requires it; deserialization defaulting a Long wrapper to null.","solutions":["Set every epoch field to a real non-negative millisecond timestamp (System.currentTimeMillis() or the server-provided value).","Do not use negative sentinels; if a value is unknown, confirm whether the field is truly optional — for these fields the validator requires non-null.","For server-managed fields (createTime/updateTime/metaVersion), pass through the values returned by the server rather than recomputing or nulling them.","Guard with (v != null && v >= 0) before submission."],"exampleFix":"// before\nitem.setLastUpdatedTime(-1L);    // negative -> rejected\nagent.setMetaVersion(null);      // null -> rejected\n// after\nitem.setLastUpdatedTime(System.currentTimeMillis());\nagent.setMetaVersion(serverMetaVersion); // non-negative long","handlingStrategy":"validation","validationCode":"static void requireEpoch(Long v, String field) {\n    if (v == null || v < 0) {\n        throw new IllegalArgumentException(field + \" must be a non-negative integer\");\n    }\n}\nrequireEpoch(agent.getMetaVersion(), \"metaVersion\");\nrequireEpoch(agent.getCreateTime(), \"createTime\");\nrequireEpoch(agent.getUpdateTime(), \"updateTime\");","typeGuard":"static boolean epochOk(Long v) {\n    return v != null && v >= 0L;\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().endsWith(\"must be a non-negative integer\")) {\n        // set the named field to System.currentTimeMillis() or server value\n    } else throw e;\n}","preventionTips":["metaVersion/createTime/updateTime/lastUpdatedTime must be non-null >= 0.","Never use -1 as a sentinel; these fields are not optional.","Pass through server-managed timestamps rather than recomputing them."],"tags":["ai-agent","validation","timestamp","required-field"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}