flowable/flowable-engine · critical · FlowableException

Cannot start process instance. Process model

Error message

Cannot start process instance. Process model ${name} (id = ${id}) could not be found

What it means

Flowable throws this when the in-memory BPMN process model for a resolved ProcessDefinition cannot be loaded from the deployment cache during process instance creation. ProcessDefinitionUtil.getProcess() returned null even though the definition entity exists, meaning the parsed model is unavailable. The engine refuses to continue because it needs the FlowElements to start execution.

Solutions

1. Redeploy the BPMN process model so the definition and its parsed model are rebuilt and cached.
2. Restart the process engine (or clear the process definition/deployment cache) so the model is reloaded from ACT_GE_BYTEARRAY.
3. Verify the deployment resources still exist in ACT_GE_BYTEARRAY; if deleted, redeploy and start with the new definition.
4. Check custom ProcessEngineConfiguration.getDeploymentManager/ProcessDefinitionCacheLimit implementations for cache eviction bugs.
5. If on a cluster, ensure all nodes are upgraded to the same Flowable version and share a consistent cache.

Example fix

// before
ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey("order").singleResult();
runtimeService.startProcessInstanceById(def.getId()); // model may be missing from cache
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey("order").latestVersion().singleResult();
if (def == null) throw new IllegalStateException("Deploy the 'order' process first");
repositoryService.createDeployment().addClasspathResource("processes/order.bpmn20.xml").deploy(); // ensures model is deployed+cached
runtimeService.startProcessInstanceById(def.getId());

ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionId(defId).singleResult();
if (def == null) throw new IllegalStateException("Definition not deployed: " + defId);
// ensure model resolvable
BpmnModel model = repositoryService.getBpmnModel(defId);
if (model == null || model.getMainProcess() == null || model.getMainProcess().getFlowElements().isEmpty()) {
    throw new IllegalStateException("Parsed model unavailable for " + defId + " — redeploy the BPMN resource");
}

try {
    runtimeService.startProcessInstanceById(defId);
} catch (FlowableException e) {
    if (e.getMessage().contains("could not be found")) {
        repositoryService.createDeployment().addClasspathResource("processes/order.bpmn20.xml").deploy();
        runtimeService.startProcessInstanceById(defId);
    } else { throw e; }
}

When it happens

Trigger: Calling RuntimeService.startProcessInstanceByKey/ById (or any variant routed through ProcessInstanceHelper.createProcessInstance) when ProcessDefinitionUtil.getProcess(processDefinition.getId()) returns null — i.e. the definition exists in ACT_RE_PROCDEF but its parsed BPMN model is absent from the deployment/process definition cache.

Common situations: Corrupted or manually pruned deployment cache; definitions deployed by an older engine version with an incompatible cache entry; multi-node setups sharing a database but not the cache after partial cache eviction; custom cache implementations returning null on miss; database rows manually manipulated (definition kept but deployment resources deleted).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Expected an activity behavior in flow node
• No process definition found for key
• No process definition found for key
• Process model for could not be found
• Process model (id = ) could not be found for

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

Appendix: source

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

            String callbackId, String callbackType, String referenceId, String referenceType, String ownerId, String assigneeId,
            String stageInstanceId, boolean startProcessInstance) {

        CommandContext commandContext = Context.getCommandContext();
        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            return compatibilityHandler.startProcessInstance(processDefinition.getKey(), processDefinition.getId(),
                    variables, transientVariables, businessKey, processDefinition.getTenantId(), processInstanceName);
        }

        // Do not start process a process instance if the process definition is suspended
        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();
        }

View on GitHub (pinned to d6d39ce1c6)