{"record":{"id":"0e3ac11f416571b2","repo":"flowable/flowable-engine","slug":"processdefinitionkey-and-processdefinitionid-are-n-0e3ac1","errorCode":null,"errorMessage":"processDefinitionKey and processDefinitionId are null","messagePattern":"processDefinitionKey and processDefinitionId are null","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java","lineNumber":93,"sourceCode":"        // Find the process definition\n        ProcessDefinition processDefinition = null;\n        if (processDefinitionId != null) {\n            processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for id = '\" + processDefinitionId + \"'\", ProcessDefinition.class);\n            }\n        } else if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {\n            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitionKey);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"'\", ProcessDefinition.class);\n            }\n        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\n            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"' for tenant identifier \" + tenantId, ProcessDefinition.class);\n            }\n        } else {\n            throw new ActivitiIllegalArgumentException(\"processDefinitionKey and processDefinitionId are null\");\n        }\n\n        // Do not start process a process instance if the process definition is suspended\n        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {\n            throw new ActivitiException(\"Cannot start process instance. Process definition \"\n                    + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") is suspended\");\n        }\n\n        // Start the process instance\n        ExecutionEntity processInstance = ((ProcessDefinitionEntity) processDefinition).createProcessInstance(businessKey);\n\n        // now set the variables passed into the start command\n        initializeVariables(processInstance);\n\n        // now set processInstance name\n        if (processInstanceName != null) {\n            processInstance.setName(processInstanceName);\n            commandContext.getHistoryManager().recordProcessInstanceNameChange(processInstance.getId(), processInstanceName);","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java#L75-L111","documentation":"Thrown by StartProcessInstanceCmd.execute() as ActivitiIllegalArgumentException when neither processDefinitionId nor processDefinitionKey is set, so the command has no way to resolve which process to start. This is a programmer/input error guard at the start of definition resolution.","triggerScenarios":"Calling RuntimeService.startProcessInstanceById(null) / startProcessInstanceByKey(null), or building a ProcessInstantiationBuilder without calling processDefinitionId/Key/tenantId before start(); message/CQRS handlers forwarding null definition identifiers.","commonSituations":"Configuration properties left empty (null definition key from properties/YAML); variables or request DTOs with missing process key fields passed straight into the runtime service; test code instantiating the command directly.","solutions":["Pass a valid key: runtimeService.startProcessInstanceByKey(\"orderProcess\").","If identifiers come from config/requests, fail fast upstream with a clear validation message when null/blank.","When using ProcessInstantiationBuilder, ensure processDefinitionKey(...) or processDefinitionId(...) is invoked before .start().","Review the caller that produced the null id/key — often an unset environment variable or missing request field."],"exampleFix":"// before\nString key = config.get(\"process.key\"); // null\nruntimeService.startProcessInstanceByKey(key); // ActivitiIllegalArgumentException\n// after\nString key = config.get(\"process.key\");\nObjects.requireNonNull(key, \"process.key must be configured\");\nruntimeService.startProcessInstanceByKey(key);","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(definitionKey, \"processDefinitionKey must not be null\");\nif (definitionKey.isBlank()) {\n    throw new IllegalArgumentException(\"processDefinitionKey must not be blank\");\n}","typeGuard":null,"tryCatchPattern":"if (definitionKey == null || definitionKey.isBlank()) {\n    throw new IllegalArgumentException(\"processDefinitionKey is required\");\n}\ntry {\n    return runtimeService.startProcessInstanceByKey(definitionKey, vars);\n} catch (ActivitiIllegalArgumentException e) {\n    throw new IllegalStateException(\"Engine rejected null definition reference\", e);\n}","preventionTips":["Validate config-driven keys at application startup, not at start-time","Fail fast on null request fields before invoking the runtime service","When using ProcessInstantiationBuilder, always call processDefinitionKey/Id before start()","Write a unit test covering the missing-key path"],"tags":["null-argument","process-definition","workflow","input-validation"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}