alibaba/nacos · error · IllegalArgumentException

{fieldName} must not be null

Error message

{fieldName} must not be null

What it means

Thrown by the private requireNonNull helper when any required object field passed to the validator is null. This is the generic null-guard reused across the whole validator; the fieldName in the message identifies exactly which field was null. Examples include the top-level 'agent'/'summary'/'runtimeEndpointSnapshot' root objects, 'versionInfo', 'callInterfaces', 'endpointSourceOrder', per-item 'runtimeEndpointSnapshot item', 'runtimeEndpointSnapshot.bindings', 'runtime Endpoint state/enabled/healthy', 'versionCatalog entry', 'Endpoint', and 'runtime Version binding'.

Source

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

    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. Populate every required object before calling validateAgent / validateAgentSummary / validateRuntimeEndpointSnapshot; consult the message's fieldName to find the null slot.
2. For Boolean wrappers (enabled/healthy) on snapshot items, set explicit true/false rather than leaving null.
3. Initialize collections to non-null (even if empty where emptiness is allowed) and ensure list elements are non-null.
4. If a field is genuinely optional in your model, confirm it is optional in the validator too — many of these (e.g. versionInfo, callInterfaces) are mandatory.

Example fix

// before
item.setEnabled(null);   // rejected: 'runtime Endpoint enabled must not be null'
agent.setVersionInfo(null); // rejected: 'versionInfo must not be null'
// after
item.setEnabled(false);
agent.setVersionInfo(new AgentVersionInfo());

import java.util.Objects;
Objects.requireNonNull(agent, "agent");
Objects.requireNonNull(agent.getVersionInfo(), "versionInfo");
// for snapshot items:
for (RuntimeEndpointSnapshotItem it : snapshot.getItems()) {
    Objects.requireNonNull(it, "runtimeEndpointSnapshot item");
    Objects.requireNonNull(it.getBindings(), "runtimeEndpointSnapshot.bindings");
    Objects.requireNonNull(it.getState(), "runtime Endpoint state");
    Objects.requireNonNull(it.getEnabled(), "runtime Endpoint enabled");
    Objects.requireNonNull(it.getHealthy(), "runtime Endpoint healthy");
}

static boolean noNullRequiredFields(RuntimeEndpointSnapshotItem it) {
    return it != null && it.getEndpoint() != null && it.getBindings() != null
        && it.getState() != null && it.getEnabled() != null && it.getHealthy() != null;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("must not be null")) {
        // the fieldName prefix names the exact null slot; populate it and retry
    } else throw e;
}

When it happens

Trigger: Any Agent/snapshot validation call where a required sub-object is null: validateAgent(agent) with agent=null; an Agent with versionInfo=null; a CallInterface list null; a RuntimeEndpointSnapshotItem with null bindings/state/enabled/healthy; a null Endpoint inside a list; a null RuntimeVersionBinding.

Common situations: Partial JSON payloads missing required nested objects; a deserializer that leaves wrapper Booleans (enabled/healthy) null; forgetting to initialize collections (callInterfaces, bindings); null Endpoint entries in a list; chaining builders that skip required nodes.

Related errors

• 20002
• {fieldName} must be a non-negative integer
• Invalid agentName: {agentName}
• 20002
• 10000

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