{"record":{"id":"32079d8fd2695127","repo":"flowable/flowable-engine","slug":"process-definition-id-or-key-cannot-be-null-32079d","errorCode":null,"errorMessage":"Process definition id or key cannot be null","messagePattern":"Process definition id or key cannot be null","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java","lineNumber":93,"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 ActivitiIllegalArgumentException(\"Process definition id or key cannot be null\");\r\n        }\r\n\r\n        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<>();\r\n        ProcessDefinitionEntityManager processDefinitionManager = commandContext.getProcessDefinitionEntityManager();\r\n\r\n        if (processDefinitionId != null) {\r\n\r\n            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findProcessDefinitionById(processDefinitionId);\r\n            if (processDefinitionEntity == null) {\r\n                throw new ActivitiObjectNotFoundException(\"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":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java#L75-L111","documentation":"AbstractSetProcessDefinitionStateCmd.findProcessDefinition() validates that at least one of processDefinitionId or processDefinitionKey is set before querying. If both are null (ActivitiIllegalArgumentException is thrown). The command (suspend/activate process definition) cannot locate any definition without one of these identifiers.","triggerScenarios":"Calling SetProcessDefinitionStateCmd-derived commands (e.g. repositoryService.activateProcessDefinition()/suspendProcessDefinition()) with neither the id nor the key supplied.","commonSituations":"Programmatic suspension/activation built dynamically where both parameters end up null; custom code constructing the command object without setting fields; passing only unrelated query parameters.","solutions":["Pass processDefinitionId (activateProcessDefinitionById / suspendProcessDefinitionById) when the exact definition id is known.","Otherwise pass processDefinitionKey (activateProcessDefinitionByKey / suspendProcessDefinitionByKey).","Validate your input map/request: ensure the identifier parameter is not being lost or misnamed before invoking the API.","Ensure you are not shadowing the id/key fields with null defaults when constructing the command."],"exampleFix":"// before\nrepositoryService.suspendProcessDefinition(new SuspendProcessDefinitionCmd(null, null, false, null, null));\n// after\nrepositoryService.suspendProcessDefinitionByKey(\"orderProcess\");","handlingStrategy":"validation","validationCode":"if (id == null && key == null) { throw new IllegalArgumentException(\"Provide processDefinitionId or processDefinitionKey\"); }","typeGuard":null,"tryCatchPattern":"try { repositoryService.suspendProcessDefinition(id, key, false, null, tenantId); } catch (ActivitiIllegalArgumentException e) { if (e.getMessage().contains(\"id or key cannot be null\")) { throw new IllegalArgumentException(\"caller must supply id or key\"); } throw e; }","preventionTips":["Validate inputs before calling suspend/activate APIs.","Prefer by-key operations for latest-version semantics.","Beware default-null parameters when building the call dynamically."],"tags":["illegal-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"}