{"record":{"id":"87e0a0440e75c1cc","repo":"alibaba/nacos","slug":"fieldname-must-not-be-null-87e0a0","errorCode":null,"errorMessage":"{fieldName} must not be null","messagePattern":"(.+?) must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":661,"sourceCode":"    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":643,"sourceCodeEnd":666,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L643-L666","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Populate every required object before calling validateAgent / validateAgentSummary / validateRuntimeEndpointSnapshot; consult the message's fieldName to find the null slot.","For Boolean wrappers (enabled/healthy) on snapshot items, set explicit true/false rather than leaving null.","Initialize collections to non-null (even if empty where emptiness is allowed) and ensure list elements are non-null.","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."],"exampleFix":"// before\nitem.setEnabled(null);   // rejected: 'runtime Endpoint enabled must not be null'\nagent.setVersionInfo(null); // rejected: 'versionInfo must not be null'\n// after\nitem.setEnabled(false);\nagent.setVersionInfo(new AgentVersionInfo());","handlingStrategy":"validation","validationCode":"import java.util.Objects;\nObjects.requireNonNull(agent, \"agent\");\nObjects.requireNonNull(agent.getVersionInfo(), \"versionInfo\");\n// for snapshot items:\nfor (RuntimeEndpointSnapshotItem it : snapshot.getItems()) {\n    Objects.requireNonNull(it, \"runtimeEndpointSnapshot item\");\n    Objects.requireNonNull(it.getBindings(), \"runtimeEndpointSnapshot.bindings\");\n    Objects.requireNonNull(it.getState(), \"runtime Endpoint state\");\n    Objects.requireNonNull(it.getEnabled(), \"runtime Endpoint enabled\");\n    Objects.requireNonNull(it.getHealthy(), \"runtime Endpoint healthy\");\n}","typeGuard":"static boolean noNullRequiredFields(RuntimeEndpointSnapshotItem it) {\n    return it != null && it.getEndpoint() != null && it.getBindings() != null\n        && it.getState() != null && it.getEnabled() != null && it.getHealthy() != null;\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().endsWith(\"must not be null\")) {\n        // the fieldName prefix names the exact null slot; populate it and retry\n    } else throw e;\n}","preventionTips":["The fieldName in the message names exactly which slot is null.","Set Boolean wrappers (enabled/healthy) to explicit true/false.","Initialize collections non-null and ensure list elements are non-null.","Confirm which fields are truly optional vs required before omitting them."],"tags":["ai-agent","validation","null-check","required-field"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}