flowable/flowable-engine · error · FlowableException

Cannot start a sub process instance. Process model " +…

Error message

Cannot start a sub process instance. Process model " + subProcessDefinition.getName() + " (id = " + subProcessDefinition.getId() + ") could not be found

What it means

Thrown when starting a sub process instance for a CallActivity during process instance migration: ProcessDefinitionUtil.getProcess() returned null for the target sub process definition, meaning the BPMN model for that definition could not be resolved from the repository. The engine cannot build the sub process instance without its model, so it fails fast.

Solutions

1. Deploy the BPMN file containing the called sub process so a resolvable definition exists for the call activity
2. Verify the CallActivity 'called element' key matches the sub process process id (and tenant handling) in the new definition
3. Check ACT_RE_PROCDEF for the sub process definition id; redeploy if the definition row exists but the model can't be parsed
4. Clear/refresh the deployment cache or restart the engine if the repository and cache are out of sync

Example fix

// before (target def references 'orderSubProcess' never deployed)
migrationBuilder.migrateTo(newDefId);
// after: deploy the sub process first
repositoryService.createDeployment().addClasspathResource("orderSubProcess.bpmn20.xml").tenantId(tenant).deploy();
migrationBuilder.migrateTo(newDefId);

ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(calledElement).latestVersion().singleResult();
if (def == null) throw new IllegalStateException("Deploy called sub process before migrating: " + calledElement);

try {
    migrationBuilder.migrateTo(newDefId);
} catch (FlowableException ex) {
    if (ex.getMessage().contains("could not be found")) {
        // deploy missing sub process model and retry
    } else throw ex;
}

When it happens

Trigger: Migrating (or changing) a process instance whose new definition contains a CallActivity while the called sub process definition cannot be resolved — the model was not deployed, the definition is in another tenant/app engine, or the deployment cache/repository is inconsistent.

Common situations: Missing deployment of the called process in the target definition's deployment; multi-tenant setups where the call activity does not resolve the tenant-specific sub process; referencing a sub process definition that was deleted or deployed to a different Flowable app engine.

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

• byte array for resource
• byte array for resource
• byte array for resource
• bytes array is null
• bytes is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/dynamic/AbstractDynamicStateManager.java:1091

            childExecutionEntity.setScope(false);

            CommandContextUtil.getProcessEngineConfiguration().getActivityInstanceEntityManager().recordActivityStart(childExecutionEntity);

            ActivityBehavior boundaryEventBehavior = ((ActivityBehavior) boundaryEvent.getBehavior());
            LOGGER.debug("Executing boundary event activityBehavior {} with execution {}", boundaryEventBehavior.getClass(), childExecutionEntity.getId());
            boundaryEventBehavior.execute(childExecutionEntity);
        }
    }

    protected ExecutionEntity createCallActivityInstance(CallActivity callActivity, ProcessDefinition subProcessDefinition, ExecutionEntity parentExecution, String initialActivityId, CommandContext commandContext) {

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

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

        String businessKey = null;

        if (!StringUtils.isEmpty(callActivity.getBusinessKey())) {
            Expression expression = expressionManager.createExpression(callActivity.getBusinessKey());
            businessKey = expression.getValue(parentExecution).toString();

        } else if (callActivity.isInheritBusinessKey()) {
            ExecutionEntity processInstance = executionEntityManager.findById(parentExecution.getProcessInstanceId());
            businessKey = processInstance.getBusinessKey();
        }

        ExecutionEntity subProcessInstance = executionEntityManager.createSubprocessInstance(subProcessDefinition, parentExecution, businessKey, initialActivityId);
        if (processEngineConfiguration.isEnableEntityLinks()) {
            EntityLinkUtil.createEntityLinks(parentExecution.getProcessInstanceId(), parentExecution.getId(), callActivity.getId(),
                    subProcessInstance.getId(), ScopeTypes.BPMN);
        }

View on GitHub (pinned to d6d39ce1c6)