{"record":{"id":"21dc021c91d46588","repo":"alibaba/nacos","slug":"agent-direct-online-request-must-not-be-null","errorCode":null,"errorMessage":"Agent direct-online request must not be null","messagePattern":"Agent direct-online request must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java","lineNumber":771,"sourceCode":"            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {\n            throw illegalState(\"Agent Version cannot be restored online from status \" + status\n                + \": \" + agentName + '@' + version);\n        }\n        persistenceService.updateVersionStatus(namespaceId, agentName, version,\n            AiConstants.Agent.VERSION_STATUS_ONLINE);\n        persistenceService.synchronizeDerivedState(namespaceId, agentName,\n            setAsLatest ? version : null, null,\n            AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status) ? version : null,\n            AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)\n                || AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status) ? version : null);\n        return persistenceService.getAgentVersion(namespaceId, agentName, version);\n    }\n    \n    private void validateDirectOnlineRequest(String namespaceId,\n        AgentDraftCreateRequest request) {\n        if (request == null) {\n            throw new IllegalArgumentException(\"Agent direct-online request must not be null\");\n        }\n        AgentValidationUtils.validateNamespaceId(namespaceId);\n        request.validate();\n        if (request.getCallInterfaces() == null || StringUtils.isNotBlank(\n            request.getBasedOnVersion())) {\n            throw new IllegalArgumentException(\n                \"Agent direct-online request must contain callInterfaces\");\n        }\n    }\n    \n    private AgentVersionDetail toOnlineVersion(AgentDraftCreateRequest request) {\n        AgentVersionDetail result = new AgentVersionDetail();\n        result.setVersion(request.getVersion());\n        result.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE);\n        result.setCallInterfaces(request.getCallInterfaces());\n        result.setAuthor(request.getAuthor());\n        result.setChangeDescription(request.getChangeDescription());\n        return result;","sourceCodeStart":753,"sourceCodeEnd":789,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java#L753-L789","documentation":"Thrown by AgentOperationService.validateDirectOnlineRequest as an IllegalArgumentException when the direct-online request parameter is null. This is a precondition guard for the direct-online registration path (registering a version that goes straight to ONLINE status without a draft cycle). Unchecked exception, not a NacosApiException.","triggerScenarios":"Calling the direct-online registration path with a null request object. Controller deserialization producing null from an empty body. Code path where the request is conditionally constructed.","commonSituations":"Empty request body on the direct-online endpoint. JSON parse failure yielding null. Refactoring that removed request construction in a branch.","solutions":["Validate the request is non-null at the controller before calling the direct-online path.","Ensure the client always sends a complete request body for direct-online registration.","Return HTTP 400 at the controller layer if the body is missing."],"exampleFix":"// before\nservice.registerDirectOnline(ns, null);\n\n// after\nif (request == null) {\n    return ResponseEntity.badRequest().body(\"direct-online request required\");\n}\nservice.registerDirectOnline(ns, request);","handlingStrategy":"type-guard","validationCode":"// Null-check at the controller before calling direct-online\nif (request == null) {\n    return ResponseEntity.badRequest().body(\"direct-online request body is required\");\n}\nagentOperationService.registerDirectOnline(ns, request);","typeGuard":"public static boolean isValidDirectOnlineRequest(AgentDraftCreateRequest request) {\n    return request != null;\n}","tryCatchPattern":"try {\n    agentOperationService.registerDirectOnline(ns, request);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"must not be null\")) {\n        return ResponseEntity.badRequest().body(e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Validate the request body is non-null at the controller boundary.","Use @NotNull on the controller's request parameter.","Return 400 early for missing bodies."],"tags":["agent","null-check","illegal-argument","direct-online","programming-error"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}