{"record":{"id":"df06611d40013606","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-initial-activity-wh","errorCode":null,"errorMessage":"Cannot start process instance, initial activity where the process instance should start is null.","messagePattern":"Cannot start process instance, initial activity where the process instance should start is null\\.","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/pvm/process/ProcessDefinitionImpl.java","lineNumber":62,"sourceCode":"        processDefinition = this;\n    }\n\n    @Override\n    public PvmProcessInstance createProcessInstance() {\n        if (initial == null) {\n            throw new ActivitiException(\n                    \"Process '\" + name + \"' has no default start activity (e.g. none start event), hence you cannot use 'startProcessInstanceBy...' but have to start it using one of the modeled start events (e.g. message start events).\");\n        }\n        return createProcessInstanceForInitial(initial);\n    }\n\n    /**\n     * creates a process instance using the provided activity as initial\n     */\n    public PvmProcessInstance createProcessInstanceForInitial(ActivityImpl initial) {\n\n        if (initial == null) {\n            throw new ActivitiException(\"Cannot start process instance, initial activity where the process instance should start is null.\");\n        }\n\n        InterpretableExecution processInstance = newProcessInstance(initial);\n        processInstance.setProcessDefinition(this);\n        processInstance.setProcessInstance(processInstance);\n        processInstance.initialize();\n\n        InterpretableExecution scopeInstance = processInstance;\n\n        List<ActivityImpl> initialActivityStack = getInitialActivityStack(initial);\n\n        for (ActivityImpl initialActivity : initialActivityStack) {\n            if (initialActivity.isScope()) {\n                scopeInstance = (InterpretableExecution) scopeInstance.createExecution();\n                scopeInstance.setActivity(initialActivity);\n                if (initialActivity.isScope()) {\n                    scopeInstance.initialize();\n                }","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/pvm/process/ProcessDefinitionImpl.java#L44-L80","documentation":"ActivitiException thrown by ProcessDefinitionImpl.createProcessInstanceForInitial when the explicitly supplied initial activity is null. Unlike createProcessInstance() (which gives the friendlier 'no default start activity' error), this overload requires the caller to name the start activity and receives no useful default. It is a defensive null check on the internal entry point.","triggerScenarios":"Calling processDefinition.createProcessInstanceForInitial(null), typically from engine-internal code paths or custom code that resolves the initial activity dynamically and got null.","commonSituations":"Custom deployment/model resolution where the start activity lookup returned null, or reflection/internal misuse of the PVM API.","solutions":["Pass a valid ActivityImpl from the same process definition (e.g. the result of getInitial() after verifying it is non-null).","Check why the initial activity resolved to null before calling this method.","Use createProcessInstance() and fix the missing none start event instead (see error 4745)."],"exampleFix":"// before\nActivityImpl initial = def.findActivity(startId); // may be null\ndef.createProcessInstanceForInitial(initial);\n// after\nActivityImpl initial = def.findActivity(startId);\nif (initial == null) {\n  throw new IllegalArgumentException(\"unknown start activity \" + startId);\n}\ndef.createProcessInstanceForInitial(initial);","handlingStrategy":"validation","validationCode":"if (initial == null) {\n  throw new IllegalArgumentException(\"initial activity must resolve to a non-null ActivityImpl\");\n}\ndefinition.createProcessInstanceForInitial(initial);","typeGuard":null,"tryCatchPattern":"try {\n  definition.createProcessInstanceForInitial(initial);\n} catch (ActivitiException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"initial activity\")) {\n    log.error(\"Resolved initial activity was null; check start-event resolution\");\n  }\n  throw e;\n}","preventionTips":["Always resolve the initial ActivityImpl via findActivity/getInitial and null-check before the call.","Prefer createProcessInstance() unless you explicitly control the start activity."],"tags":["java","pvm","null-argument","process-instance"],"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"}