Activiti/Activiti · error · ActivitiException

No start element found for process definition

Error message

No start element found for process definition ${processDefinitionID}

What it means

A BPMN process model must declare exactly one start event (none start event) for regular instantiation. When process.getInitialFlowElement() is null, getInitialFlowElement throws ActivitiException because the engine cannot determine where execution should begin.

Solutions

Add <startEvent id="start"/> with an outgoing flow as the first element of the process
For message-start-only models, start via runtimeService.startProcessInstanceByMessage(messageName) instead of by key
Validate the model: repositoryService.getBpmnModel(id) and check getMainProcess().getInitialFlowElement() != null before starting
Re-export/redeploy the corrected BPMN file

Example fix

// before (BPMN)
<process id="invoiceProcess">
  <serviceTask id="t1" .../>
<!-- after -->
<process id="invoiceProcess">
  <startEvent id="start"/>
  <sequenceFlow id="f1" sourceRef="start" targetRef="t1"/>
  <serviceTask id="t1" .../>

Defensive patterns

Strategy: validation

Validate before calling

BpmnModel model = repositoryService.getBpmnModel(definitionId);
if (model.getMainProcess().getInitialFlowElement() == null) {
    throw new IllegalStateException("Process " + definitionId + " has no start event");
}

Try / catch

try {
    runtimeService.startProcessInstanceById(definitionId);
} catch (ActivitiException e) {
    if (e.getMessage().startsWith("No start element found")) {
        // fix BPMN and redeploy, or start by message if it's a message-start model
    }
}

Prevention

Always include a <startEvent> as the first element of every process
Validate BPMN models in CI with the engine's schema validation
Use message/signal start APIs for models that have no none start event

When it happens

Trigger: Starting a process instance by key/id whose BPMN XML has no <startEvent>, or where startEvent is not the first flow element (e.g., model starts with a message/timer start event only and the caller starts without a message/signal).

Common situations: Hand-edited BPMN missing startEvent; models designed only for message start events started via startProcessInstanceByKey; diagram tools exporting incomplete process XML.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/f82d5ed9fc79b012. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/util/ProcessInstanceHelper.java:81

        }

        Process process = ProcessDefinitionUtil.getProcess(processDefinition.getId());
        if (process == null) {
            throw new ActivitiException(
                "Cannot start process instance. Process model " +
                processDefinition.getName() +
                " (id = " +
                processDefinition.getId() +
                ") could not be found"
            );
        }
        return process;
    }

    public FlowElement getInitialFlowElement(Process process, String processDefinitionID) {
        FlowElement initialFlowElement = process.getInitialFlowElement();
        if (initialFlowElement == null) {
            throw new ActivitiException("No start element found for process definition " + processDefinitionID);
        }
        return initialFlowElement;
    }

    public ProcessInstance createAndStartProcessInstance(ProcessInstanceCreationOptions options) {
        Process process = this.getActiveProcess(options.getProcessDefinition());
        FlowElement initialFlowElement = this.getInitialFlowElement(process, options.getProcessDefinition().getId());

        return createAndStartProcessInstanceWithInitialFlowElement(options, initialFlowElement, process, true);
    }

    public ProcessInstance createProcessInstance(
        ProcessDefinition processDefinition,
        String businessKey,
        String processInstanceName,
        Map<String, Object> variables,
        Map<String, Object> transientVariables
    ) {

View on GitHub (pinned to 56435b1a97)