{"record":{"id":"6fec96f2ce50bd76","repo":"flowable/flowable-engine","slug":"process-definition-id-or-key-cannot-be-null","errorCode":null,"errorMessage":"Process definition id or key cannot be null","messagePattern":"Process definition id or key cannot be null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java","lineNumber":113,"sourceCode":"            createTimerForDelayedExecution(commandContext, processDefinitions);\r\n        } else { // Process definition state is changed now\r\n            changeProcessDefinitionState(commandContext, processDefinitions);\r\n        }\r\n\r\n        return null;\r\n    }\r\n\r\n    protected List<ProcessDefinitionEntity> findProcessDefinition(CommandContext commandContext) {\r\n\r\n        // If process definition is already provided (eg. when command is called through the DeployCmd)\r\n        // we don't need to do an extra database fetch and we can simply return it, wrapped in a list\r\n        if (processDefinitionEntity != null) {\r\n            return Collections.singletonList(processDefinitionEntity);\r\n        }\r\n\r\n        // Validation of input parameters\r\n        if (processDefinitionId == null && processDefinitionKey == null) {\r\n            throw new FlowableIllegalArgumentException(\"Process definition id or key cannot be null\");\r\n        }\r\n\r\n        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<>();\r\n        ProcessDefinitionEntityManager processDefinitionManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);\r\n\r\n        if (processDefinitionId != null) {\r\n\r\n            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findById(processDefinitionId);\r\n            if (processDefinitionEntity == null) {\r\n                throw new FlowableObjectNotFoundException(\"Cannot find process definition for id '\" + processDefinitionId + \"'\", ProcessDefinition.class);\r\n            }\r\n            processDefinitionEntities.add(processDefinitionEntity);\r\n\r\n        } else {\r\n\r\n            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(processDefinitionKey);\r\n\r\n            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\r","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java#L95-L131","documentation":"findProcessDefinition in AbstractSetProcessDefinitionStateCmd validates that at least one of processDefinitionId or processDefinitionKey was supplied when changing a process definition's state (suspend/activate). If both are null this FlowableIllegalArgumentException is thrown.","triggerScenarios":"Building a Suspend/ActivateProcessDefinitionCmd (e.g. via managementService.activateProcessDefinitionById/ByKey builders or process definition state commands) without calling either setter, or passing null explicitly.","commonSituations":"Programmatically built commands where fields are set conditionally and both branches were skipped; copy-paste of command wiring that forgot the selector.","solutions":["Set the selector: managementService.activateProcessDefinitionByKey(key) or byId(id)","Add a caller-side null check before executing the command","Include tenantId with key when using key-based selection in multi-tenant setups"],"exampleFix":"// before\nSuspendProcessDefinitionBuilder b = managementService.suspendProcessDefinition();\nb.suspend(); // no id/key -> throws\n// after\nmanagementService.suspendProcessDefinition()\n    .processDefinitionKey(\"orderProcess\")\n    .suspend();","handlingStrategy":"validation","validationCode":"if (processDefinitionId == null && processDefinitionKey == null) {\n    throw new IllegalArgumentException(\"Provide processDefinitionId or processDefinitionKey\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    managementService.suspendProcessDefinition()...;\n} catch (FlowableIllegalArgumentException e) {\n    // command misconfigured; fix builder wiring\n}","preventionTips":["Always call exactly one selector method on the builder before executing","Wrap builder construction in a helper that enforces id-or-key presence","Unit-test command builders for the both-null case"],"tags":["flowable","null-argument","validation","process-definition"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}