{"record":{"id":"a5e02693bfa11929","repo":"alibaba/nacos","slug":"labels-must-not-be-null","errorCode":null,"errorMessage":"labels must not be null","messagePattern":"labels must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentLabelsUpdateRequest.java","lineNumber":45,"sourceCode":" *\n * @author Nacos\n */\n@JsonInclude(JsonInclude.Include.NON_NULL)\npublic class AgentLabelsUpdateRequest implements Serializable {\n    \n    private static final long serialVersionUID = 1L;\n    \n    private String agentName;\n    \n    private Map<String, String> labels;\n    \n    /**\n     * Validate custom labels and their exact Version targets.\n     */\n    public void validate() {\n        AgentAdminRequestUtils.validateIdentity(agentName);\n        if (labels == null) {\n            throw new IllegalArgumentException(\"labels must not be null\");\n        }\n        for (Map.Entry<String, String> entry : labels.entrySet()) {\n            AgentValidationUtils.validateNonLatestLabel(entry.getKey());\n            AgentAdminRequestUtils.validateVersion(entry.getValue());\n        }\n    }\n    \n    public String getAgentName() {\n        return agentName;\n    }\n    \n    public void setAgentName(String agentName) {\n        this.agentName = agentName;\n    }\n    \n    public Map<String, String> getLabels() {\n        return labels;\n    }","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentLabelsUpdateRequest.java#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Always set labels to at least an empty Map when building the request.","If clearing labels, pass Collections.emptyMap() rather than null.","Ensure Jackson is configured to coerce missing JSON objects to empty maps if your API contract expects it."],"exampleFix":"// before\nrequest.setLabels(null); // field omitted\nrequest.validate(); // throws\n\n// after\nrequest.setLabels(java.util.Collections.emptyMap());\nrequest.validate(); // ok","handlingStrategy":"validation","validationCode":"if (request.getLabels() == null) {\n    request.setLabels(java.util.Collections.emptyMap());\n}","typeGuard":"public static boolean isLabelsUpdateValid(AgentLabelsUpdateRequest req) {\n    return req.getLabels() != null;\n}","tryCatchPattern":"try {\n    request.validate();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"labels must not be null\")) {\n        return badRequest(\"labels field is required\");\n    }\n    throw e;\n}","preventionTips":["Default labels to an empty map, not null, in your request builder.","Ensure JSON deserialization does not leave maps as null.","Document that an empty map clears labels."],"tags":["agent-admin","validation","labels","non-null"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}