{"record":{"id":"9f9e3f2d22d18951","repo":"Activiti/Activiti","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":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java","lineNumber":108,"sourceCode":"        if (executionDate != null) {\n            // Process definition state change is delayed\n            createTimerForDelayedExecution(commandContext, processDefinitions);\n        } else {\n            // Process definition state is changed now\n            changeProcessDefinitionState(commandContext, processDefinitions);\n        }\n    }\n\n    protected List<ProcessDefinitionEntity> findProcessDefinition(CommandContext commandContext) {\n        // If process definition is already provided (eg. when command is called through the DeployCmd)\n        // we don't need to do an extra database fetch and we can simply return it, wrapped in a list\n        if (processDefinitionEntity != null) {\n            return singletonList(processDefinitionEntity);\n        }\n\n        // Validation of input parameters\n        if (processDefinitionId == null && processDefinitionKey == null) {\n            throw new ActivitiIllegalArgumentException(\"Process definition id or key cannot be null\");\n        }\n\n        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<ProcessDefinitionEntity>();\n        ProcessDefinitionEntityManager processDefinitionManager = commandContext.getProcessDefinitionEntityManager();\n\n        if (processDefinitionId != null) {\n            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findById(processDefinitionId);\n            if (processDefinitionEntity == null) {\n                throw new ActivitiObjectNotFoundException(\n                    \"Cannot find process definition for id '\" + processDefinitionId + \"'\",\n                    ProcessDefinition.class\n                );\n            }\n            processDefinitionEntities.add(processDefinitionEntity);\n        } else {\n            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(\n                processDefinitionKey\n            );","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/Activiti/Activiti/blob/56435b1a97deeafdc09dd40074b056c89fba5a8a/activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java#L90-L126","documentation":"AbstractSetProcessDefinitionStateCmd.findProcessDefinition validates the input of process-definition state commands (suspend/activate process definition). If neither a processDefinitionId nor a processDefinitionKey was supplied, it throws ActivitiIllegalArgumentException with this message. Both identifying parameters are null, so the command cannot target any definition.","triggerScenarios":"Calling runtimeService.activateProcessDefinitionById(null), suspendProcessDefinitionByKey(null), or building SetProcessDefinitionStateCmd without setting id or key — e.g. passing null request parameters through REST or programmatic activation/suspension.","commonSituations":"REST/body parsing that leaves id and key null (empty request body); code paths that intended to pass a key but the variable was never populated; copy-pasted suspension code where only tenantId/params were set.","solutions":["Supply either the process definition id or key: use activateProcessDefinitionById(id)/suspendProcessDefinitionById(id) or the *ByKey variants.","Validate the caller's inputs before invoking the runtime service and fail fast with a clear message.","If the id comes from a repository lookup (e.g. ProcessDefinitionQuery), confirm that lookup returned a non-null value.","If you meant to suspend/activate all definitions of a process instance, use suspendProcessInstanceById instead."],"exampleFix":"// before\nruntimeService.suspendProcessDefinitionByKey(null);\n// after\nString key = processDefinition.getKey(); // must be non-null\nif (key == null) throw new IllegalArgumentException(\"processDefinitionKey required\");\nruntimeService.suspendProcessDefinitionByKey(key);","handlingStrategy":"validation","validationCode":"// validate before calling the runtime service\nif (processDefinitionId == null && processDefinitionKey == null) {\n    throw new IllegalArgumentException(\"Provide processDefinitionId or processDefinitionKey\");\n}","typeGuard":"boolean hasIdentifier(String id, String key) { return id != null || key != null; }","tryCatchPattern":"try {\n    runtimeService.suspendProcessDefinitionById(id);\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().contains(\"id or key cannot be null\")) {\n        // surface input validation problem to caller\n    }\n    throw e;\n}","preventionTips":["Validate REST/body inputs so id or key is always populated","Prefer key-based APIs with explicit, non-null keys","Fail fast at the service boundary on null identifiers"],"tags":["validation","process-definition","null-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"56435b1a97deeafdc09dd40074b056c89fba5a8a","analyzedAt":"2026-09-09T21:00:06.703Z","contentChangedAt":"2026-09-09T21:00:06.703Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}