alibaba/nacos · error · IllegalArgumentException

labels must not be null

Error message

labels must not be null

What it means

AgentLabelsUpdateRequest.validate requires a non-null labels map. Even if you intend to clear all labels, you must pass an empty map rather than null. Each label key is also validated via validateNonLatestLabel and each value (a version target) via validateVersion.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentLabelsUpdateRequest.java:45

 *
 * @author Nacos
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public class AgentLabelsUpdateRequest implements Serializable {
    
    private static final long serialVersionUID = 1L;
    
    private String agentName;
    
    private Map<String, String> labels;
    
    /**
     * Validate custom labels and their exact Version targets.
     */
    public void validate() {
        AgentAdminRequestUtils.validateIdentity(agentName);
        if (labels == null) {
            throw new IllegalArgumentException("labels must not be null");
        }
        for (Map.Entry<String, String> entry : labels.entrySet()) {
            AgentValidationUtils.validateNonLatestLabel(entry.getKey());
            AgentAdminRequestUtils.validateVersion(entry.getValue());
        }
    }
    
    public String getAgentName() {
        return agentName;
    }
    
    public void setAgentName(String agentName) {
        this.agentName = agentName;
    }
    
    public Map<String, String> getLabels() {
        return labels;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Always set labels to at least an empty Map when building the request.
2. If clearing labels, pass Collections.emptyMap() rather than null.
3. Ensure Jackson is configured to coerce missing JSON objects to empty maps if your API contract expects it.

Example fix

// before
request.setLabels(null); // field omitted
request.validate(); // throws

// after
request.setLabels(java.util.Collections.emptyMap());
request.validate(); // ok

if (request.getLabels() == null) {
    request.setLabels(java.util.Collections.emptyMap());
}

public static boolean isLabelsUpdateValid(AgentLabelsUpdateRequest req) {
    return req.getLabels() != null;
}

try {
    request.validate();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("labels must not be null")) {
        return badRequest("labels field is required");
    }
    throw e;
}

When it happens

Trigger: Calling labelsUpdate.validate() when labels is null. Happens when the request body omits the labels field entirely, or when a client sets it to null explicitly.

Common situations: JSON deserialization with Jackson where labels is absent in the payload (maps default to null unless configured). A client that conditionally sets labels only when there are changes. Intending to clear labels by passing null instead of an empty map.

Related errors

• callInterfaces must not be null
• PARAMETER_MISSING
• Invalid Agent resource status: {status}
• Agent draft must contain either callInterfaces or basedOnVer
• Skill cannot be null

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