flowable/flowable-engine · error · FlowableException

Provide start event id is not a start event

Error message

Provide start event id is not a start event ${startEventId} for process definition ${id}

What it means

Process model consistency failure at instance creation: the configured start event id does not resolve to an actual start event of the process definition, so the process instance cannot be started from that entry point.

Solutions

1. Use the id of an actual <startEvent> element from the BPMN XML.
2. Sanity-check the element type: Object el = repositoryService.getBpmnModel(defId).getMainProcess().getFlowElement(id); ensure el instanceof StartEvent.
3. Fix duplicate ids in the BPMN model and redeploy if a non-start element holds the id you passed.
4. Omit startEventId to use the default initial start event.

Example fix

// before
runtimeService.startProcessInstanceById(defId, "userTask1", vars); // wrong element
// after
// <startEvent id="messageStart" .../>
runtimeService.startProcessInstanceById(defId, "messageStart", vars);

FlowElement el = repositoryService.getBpmnModel(defId).getMainProcess().getFlowElement(startEventId);
if (!(el instanceof org.flowable.bpmn.model.StartEvent)) {
    throw new IllegalArgumentException("startEventId must reference a <startEvent>, got: " + (el == null ? "null" : el.getClass().getSimpleName()));
}

public static boolean isStartEventElement(FlowElement el) {
    return el instanceof org.flowable.bpmn.model.StartEvent;
}

try {
    runtimeService.startProcessInstanceById(defId, null, startEventId, vars);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Provide start event id is not a start event")) {
        throw new IllegalArgumentException("Element '" + startEventId + "' is not a start event", e);
    }
    throw e;
}

When it happens

Trigger: Calling startProcessInstanceByKey/ById with a startEventId that matches a non-start-event element in the model (task, gateway, end event, etc.).

Common situations: Copy/paste of ids between elements; a user task and start event accidentally sharing the same id in hand-edited BPMN; caller targeting the wrong id in a large diagram; generator-produced ids mixed up between diagrams.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Class does not implement
• Custom properties resolver delegate expression " +…
• Delegate expression " + expression + " did not resolve to…
• Delegate expression " + expression + " did not resolve to…
• Delegate expression " + expression + " did not resolve to…

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java:105

        if (ProcessDefinitionUtil.isProcessDefinitionSuspended(processDefinition.getId())) {
            throw new FlowableException("Cannot start process instance. Process definition " + processDefinition.getName() + " (id = " + processDefinition.getId() + ") is suspended");
        }

        // Get model from cache
        Process process = ProcessDefinitionUtil.getProcess(processDefinition.getId());
        if (process == null) {
            throw new FlowableException("Cannot start process instance. Process model " + processDefinition.getName() + " (id = " + processDefinition.getId() + ") could not be found");
        }
        
        FlowElement initialFlowElement = null;
        if (StringUtils.isNotEmpty(startEventId)) {
            FlowElement startEventFlowElement = process.getFlowElement(startEventId);
            if (startEventFlowElement == null) {
                throw new FlowableException("No start element found with id " + startEventId + " for process definition " + processDefinition.getId());
            }
            
            if (!(startEventFlowElement instanceof StartEvent)) {
                throw new FlowableException("Provide start event id is not a start event " + startEventId + " for process definition " + processDefinition.getId());
            }
            
            initialFlowElement = startEventFlowElement;
            
        } else {
            initialFlowElement = process.getInitialFlowElement();
        }
        
        if (initialFlowElement == null) {
            throw new FlowableException("No start element found for process definition " + processDefinition.getId());
        }

        return createAndStartProcessInstanceWithInitialFlowElement(processDefinition, businessKey, businessStatus, processInstanceName,
                overrideDefinitionTenantId,
                predefinedProcessInstanceId, initialFlowElement, process, variables, transientVariables,
                callbackId, callbackType, referenceId, referenceType, ownerId, assigneeId, stageInstanceId, startProcessInstance);
    }

View on GitHub (pinned to d6d39ce1c6)