alibaba/nacos · error · IllegalArgumentException

{fieldName} must be a non-negative integer

Error message

{fieldName} must be a non-negative integer

What it means

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.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:651

            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value, e);
        }
    }
    
    private static void validateRequiredLength(String value, int maximum, String fieldName) {
        if (value == null || value.isEmpty() || codePointLength(value) > maximum) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value);
        }
    }
    
    private static void validateOptionalLength(String value, int maximum, String fieldName) {
        if (value != null && codePointLength(value) > maximum) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": exceeds " + maximum);
        }
    }
    
    private static void validateEpochMillis(Long value, String fieldName) {
        if (value == null || value < 0) {
            throw new IllegalArgumentException(fieldName + " must be a non-negative integer");
        }
    }
    
    private static int codePointLength(String value) {
        return value.codePointCount(0, value.length());
    }
    
    private static <T> T requireNonNull(T value, String fieldName) {
        if (value == null) {
            throw new IllegalArgumentException(fieldName + " must not be null");
        }
        return value;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set every epoch field to a real non-negative millisecond timestamp (System.currentTimeMillis() or the server-provided value).
2. 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.
3. For server-managed fields (createTime/updateTime/metaVersion), pass through the values returned by the server rather than recomputing or nulling them.
4. Guard with (v != null && v >= 0) before submission.

Example fix

// before
item.setLastUpdatedTime(-1L);    // negative -> rejected
agent.setMetaVersion(null);      // null -> rejected
// after
item.setLastUpdatedTime(System.currentTimeMillis());
agent.setMetaVersion(serverMetaVersion); // non-negative long

static void requireEpoch(Long v, String field) {
    if (v == null || v < 0) {
        throw new IllegalArgumentException(field + " must be a non-negative integer");
    }
}
requireEpoch(agent.getMetaVersion(), "metaVersion");
requireEpoch(agent.getCreateTime(), "createTime");
requireEpoch(agent.getUpdateTime(), "updateTime");

static boolean epochOk(Long v) {
    return v != null && v >= 0L;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("must be a non-negative integer")) {
        // set the named field to System.currentTimeMillis() or server value
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 20002
• {fieldName} must not be null
• Invalid agentName: {agentName}
• 20002
• 10000

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/5270cb43d5cf4a68. Report an issue: GitHub.