flowable/flowable-engine · error · ActivitiException

Cannot start process instance, initial activity where the…

Error message

Cannot start process instance, initial activity where the process instance should start is null.

What it means

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.

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).

Example fix

// before
ActivityImpl initial = def.findActivity(startId); // may be null
def.createProcessInstanceForInitial(initial);
// after
ActivityImpl initial = def.findActivity(startId);
if (initial == null) {
  throw new IllegalArgumentException("unknown start activity " + startId);
}
def.createProcessInstanceForInitial(initial);

Defensive patterns

Strategy: validation

Validate before calling

if (initial == null) {
  throw new IllegalArgumentException("initial activity must resolve to a non-null ActivityImpl");
}
definition.createProcessInstanceForInitial(initial);

Try / catch

try {
  definition.createProcessInstanceForInitial(initial);
} catch (ActivitiException e) {
  if (e.getMessage() != null && e.getMessage().contains("initial activity")) {
    log.error("Resolved initial activity was null; check start-event resolution");
  }
  throw e;
}

Prevention

Always resolve the initial ActivityImpl via findActivity/getInitial and null-check before the call.
Prefer createProcessInstance() unless you explicitly control the start activity.

When it happens

Trigger: Calling processDefinition.createProcessInstanceForInitial(null), typically from engine-internal code paths or custom code that resolves the initial activity dynamically and got null.

Common situations: Custom deployment/model resolution where the start activity lookup returned null, or reflection/internal misuse of the PVM API.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/df06611d40013606. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/pvm/process/ProcessDefinitionImpl.java:62

        processDefinition = this;
    }

    @Override
    public PvmProcessInstance createProcessInstance() {
        if (initial == null) {
            throw new ActivitiException(
                    "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).");
        }
        return createProcessInstanceForInitial(initial);
    }

    /**
     * creates a process instance using the provided activity as initial
     */
    public PvmProcessInstance createProcessInstanceForInitial(ActivityImpl initial) {

        if (initial == null) {
            throw new ActivitiException("Cannot start process instance, initial activity where the process instance should start is null.");
        }

        InterpretableExecution processInstance = newProcessInstance(initial);
        processInstance.setProcessDefinition(this);
        processInstance.setProcessInstance(processInstance);
        processInstance.initialize();

        InterpretableExecution scopeInstance = processInstance;

        List<ActivityImpl> initialActivityStack = getInitialActivityStack(initial);

        for (ActivityImpl initialActivity : initialActivityStack) {
            if (initialActivity.isScope()) {
                scopeInstance = (InterpretableExecution) scopeInstance.createExecution();
                scopeInstance.setActivity(initialActivity);
                if (initialActivity.isScope()) {
                    scopeInstance.initialize();
                }

View on GitHub (pinned to d6d39ce1c6)