flowable/flowable-engine · critical · FlowableException

Cannot start a sub process instance. Process model ${process

Error message

Cannot start a sub process instance. Process model ${processDefinition.getName()} (id = ${processDefinition.getId()}) could not be found

What it means

Flowable's CallActivityBehavior resolves the called sub-process definition and then fetches its BPMN model from the definition cache via ProcessDefinitionUtil.getProcess(). If the model is absent from the cache/repository while the ProcessDefinition metadata exists, the engine cannot start the sub process instance and throws this FlowableException. It usually indicates repository inconsistency between process definition metadata and its deployed resource.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/CallActivityBehavior.java:106

        this.fallbackToDefaultTenant = callActivity.getFallbackToDefaultTenant();
    }

    @Override
    public void execute(DelegateExecution execution) {

        ExecutionEntity executionEntity = (ExecutionEntity) execution;
        CallActivity callActivity = (CallActivity) executionEntity.getCurrentFlowElement();
        
        CommandContext commandContext = CommandContextUtil.getCommandContext();

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);

        ProcessDefinition processDefinition = getProcessDefinition(execution, callActivity, processEngineConfiguration);

        // Get model from cache
        Process subProcess = ProcessDefinitionUtil.getProcess(processDefinition.getId());
        if (subProcess == null) {
            throw new FlowableException("Cannot start a sub process instance. Process model " + processDefinition.getName() + " (id = " + processDefinition.getId() + ") could not be found");
        }

        FlowElement initialFlowElement = subProcess.getInitialFlowElement();
        if (initialFlowElement == null) {
            throw new FlowableException("No start element found for process definition " + processDefinition.getId());
        }

        // Do not start 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");
        }

        ExecutionEntityManager executionEntityManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExpressionManager expressionManager = processEngineConfiguration.getExpressionManager();

        String businessKey = null;
        if (!StringUtils.isEmpty(callActivity.getBusinessKey())) {
            Expression expression = expressionManager.createExpression(callActivity.getBusinessKey());

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Redeploy the sub-process BPMN model so the definition resource and cache are restored, then retry.
2. Check consistency between ACT_RE_PROCDEF and ACT_GE_BYTEARRAY; repair missing resource rows for the reported definition id.
3. Clear or restart the process engine to rebuild the definition cache from the repository.
4. Verify the call activity's calledElement resolves to the intended, actually deployed process definition id.

Example fix

// before: resource manually deleted from DB, definition row left behind
DELETE FROM ACT_RE_PROCDEF WHERE ID_ = 'subProcess:1:123';
// after: redeploy the full model so metadata + resource stay consistent
repositoryService.createDeployment().addClasspathResource("processes/subProcess.bpmn20.xml").deploy();

ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult();
if (def == null) throw new IllegalStateException("Definition not deployed: " + id);

try { runtimeService.startProcessInstanceByKey("parent"); }
catch (FlowableException e) { if (e.getMessage().contains("could not be found")) { redeploySubProcessModel(); } else { throw e; } }

When it happens

Trigger: Executing a call activity whose resolved process definition id has no corresponding BPMN XML resource in the deployment cache — e.g. the definition metadata row exists (ACT_RE_PROCDEF) but the resource was deleted or the cache was evicted/never populated, or an externally supplied/incorrect processDefinitionId is used.

Common situations: Manually deleting deployment resources from ACT_GE_BYTEARRAY while leaving process definition rows; database restored/copied partially across environments; custom deployment code that creates definitions without resources; cache misconfiguration after hot-redeploy.

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

• Process model for ${executionEntity} could not be found
• Cannot start process instance. Process definition ${processD
• Process definition ${processDefinitionKey} was not found in
• deployment '' didn't put app definition '' in the cache
• No process definition found for name:

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